# Errors and status codes

> The error body shape, every status code the API returns and what to do about each, plus the no-match reasons on search.

Source: https://sightradar.com/docs/errors

## Error body

Every non-2xx response is JSON:

```json
{
  "error": "insufficient credits",
  "error_code": "insufficient_credits",
  "error_detail": {
    "code": "insufficient_credits",
    "message": "insufficient credits",
    "docs_url": "https://sightradar.com/docs/errors#insufficient_credits"
  }
}
```

`error` is human-readable and may change. `error_code`, when present, is stable and the field to branch on. The codes you can receive on the public API:

| `error_code`                                                         | Status   |
| -------------------------------------------------------------------- | -------- |
| `no_wallet`                                                          | 401      |
| `read_only_account`                                                  | 403      |
| `insufficient_credits`, `overdraft_limit_reached`                    | 402      |
| `duplicate_request_in_flight`, `duplicate_request_already_processed` | 409      |
| `already_indexed`, `index_in_progress`                               | 409      |
| `preview_expired`, `preview_consumed`                                | 409      |
| `bad_request`, `not_found`                                           | 400, 404 |
| `engine_unavailable`                                                 | 502      |
| `billing_error`, `internal_error`                                    | 500      |

Two `409`s carry their code in a top-level `code` field instead of `error_code`: `confirmation_required` and `collection_not_writable`. Not every error carries a code yet: `401` for a bad key, `413` and `429` return only `error`, and errors raised by the face engine (for example a `422` for a bad `pointId`) carry a `detail` field instead. Branch on `error_code` or `code` when present and fall back to the status.

## Status codes

| Status | Meaning                                                                                                                                                                                                                                                                                                                                                                                      | What to do                                                                                                                     |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | Bad request: missing field, undecodable image, no `url`/`gcsKey`/body, base64 in batch.                                                                                                                                                                                                                                                                                                      | Fix the request. Not charged.                                                                                                  |
| `401`  | Missing or invalid API key, or `no_wallet` when the account has no wallet yet.                                                                                                                                                                                                                                                                                                               | Check the `Authorization` header and that the key is not revoked.                                                              |
| `402`  | Wallet balance too low (`insufficient_credits`), or an account with an overdraft allowance reached its limit (`overdraft_limit_reached`).                                                                                                                                                                                                                                                    | Top up, or enable [auto-recharge](/docs/billing#auto-recharge). Control-plane calls still work.                                |
| `403`  | Account is read-only (for example a tenant alias).                                                                                                                                                                                                                                                                                                                                           | Use a key from the owning account.                                                                                             |
| `404`  | Collection, batch, key or preview not found.                                                                                                                                                                                                                                                                                                                                                 | Check the id and that it belongs to this account.                                                                              |
| `409`  | Conflict: duplicate `Idempotency-Key`, collection already deleting, restore after purge started, expired preview, a write to a soft-deleted collection (restore it) or a purged one (`POST /v1/collections/{id}/recreate` brings it back empty), or a plain delete of a non-empty collection while the destructive-intent guard is on (`confirmation_required`, retry with `?intent=erase`). | Read the `error` message; most are terminal for that request. `index_in_progress` is the exception: it sends `Retry-After: 2`. |
| `413`  | Image over the 30 MB encoded cap.                                                                                                                                                                                                                                                                                                                                                            | Downscale before upload.                                                                                                       |
| `422`  | A well-formed request with an invalid value, for example a `pointId` that is not a UUID or an `embedding` that is not exactly 512 numbers.                                                                                                                                                                                                                                                   | Fix the value. Not charged.                                                                                                    |
| `429`  | Per-key requests-per-second (50 by default) or per-account in-flight concurrency (10 by default) exceeded. These `429`s carry no `Retry-After` header.                                                                                                                                                                                                                                       | Back off with jitter and retry. Use [batch](/docs/guides/batch-and-webhooks) for bulk work.                                    |
| `502`  | Engine error.                                                                                                                                                                                                                                                                                                                                                                                | Retry. The credit hold was refunded automatically.                                                                             |
| `503`  | Not ready (readiness probe), a server-side key is unconfigured, or the face engine is briefly shedding load after repeated failures (sent with `Retry-After`).                                                                                                                                                                                                                               | Retry later, honouring `Retry-After`; check the [status page](/status).                                                        |
| `504`  | The face engine did not answer in time.                                                                                                                                                                                                                                                                                                                                                      | Retry. The credit hold was refunded automatically.                                                                             |

## Search with no match

A `200` from search can still mean "nothing found". The body carries `reason` and an empty `matches` array:

| `reason`             | Meaning                                                                       |
| -------------------- | ----------------------------------------------------------------------------- |
| `no_face`            | No face detected in the selfie.                                               |
| `low_quality_selfie` | A face was found but failed the quality gate.                                 |
| `point_not_found`    | `search-by-id` was given a `point_id` that does not exist in this collection. |

These are charged like any other successful call, because the model ran.

## Retrying safely

Add an `Idempotency-Key` header (any unique string, a UUID is fine) to billable calls. A retry under the same key never re-charges and never re-runs the model. See [core concepts](/docs/concepts#idempotency).

## SDK errors

The official SDKs raise typed errors for `401`, `402`, `404` and `429` and a base error for everything else, each carrying the status code and message. See [Python](/docs/sdks/python#errors) and [Node](/docs/sdks/node#errors).
