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.