faceping.aidocs

Errors and limits

Status codes, error bodies and rate limits.

Most errors return JSON with a human-readable message, safe to show to staff:

{ "message": "Every list must offer an entry option that doesn't use face matching." }

429 comes without a body. Everything else has a message, 413 included: a 401 says why (no key, a key that's mistyped or revoked, or a token in the wrong place), a 404 says what wasn't found, and a 415 says to send JSON. Each operation in the API reference lists the codes it can return.

Status codes#

Code Meaning
400 The request is invalid; see message. For example a field PATCH /v1/lists/{listId} can't change (only name and country can), or an ongoing list without maxAgeMonths. With a sandbox key, also a list that isn't Verify (1:1): Identify is for approved live accounts.
401 Missing, mistyped or revoked API key or sandbox key, or the account is suspended. API keys (fp_) work once your account is live; in the sandbox, use a sandbox key (fp_test_). A device token (fpd_) or enrolment link token (fpe_) in X-Api-Key is refused with a message saying what it is: a device token goes in the SDK, and you can check one with GET /v1/device in the X-Device-Token header.
402 Your plan doesn't allow this: a pilot limit reached (one list, up to 500 people, 30 days) or no active plan. Choose a plan in the dashboard.
404 Not found, or not yours: "No check-in list with that id on your account.", "No one with that personId is on this list." or "No device with that id on this list." You only ever see your own lists.
409 Conflict: with a sandbox key, a second practice list (delete the first), or a 26th person on it or an enrolment link for one (a full list refuses new links too: 25 people on a practice list; on the pilot, links stop at 500 people); enrolment closed, list ended, the consent version isn't the list's wording, the list's name or country can't change now people have enrolled, or the list has no organisation name or privacy notice link yet (live: Dashboard → Settings; practice list: set them on the list with POST /v1/lists/{listId}/widget or the list's Enrol people tab).
410 (Widget) the enrolment link has expired or was already used.
413 The request is over 15 MB, for example a photo too large to enrol: send a JPEG or PNG under 15 MB (FacePing scales it to 1280 px).
415 The body isn't JSON: "Send JSON with Content-Type: application/json." Add -H "Content-Type: application/json" to every POST and PATCH with a body.
422 No usable face in the photo.
429 Rate limit: wait and retry.

Rate limits#

Who Limit
Your API key or sandbox key 300 requests per minute
Each check-in device 300 requests per minute
People's browsers (widget) 600 requests per hour per network

Plans and billing#

Prices, the free pilot and how people are counted are on Plans and billing.