# Errors and limits

> Status codes, error bodies and rate limits.

Source: https://docs.faceping.ai/errors/

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

```json
{ "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](https://docs.faceping.ai/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](https://docs.faceping.ai/billing/#the-free-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](https://app.faceping.ai/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](https://docs.faceping.ai/billing/).
