> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedatacity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Every error code the Company Matching API returns, what it means, and what to do.

The Company Matching API uses standard HTTP status codes. Most error responses include a JSON body with a `detail` field.

## Error envelope

```json theme={null}
{
  "detail": "Human-readable description of the error."
}
```

Match on status codes in your error handling, not on the exact `detail` string — wording can change between releases.

<Note>
  **`429` is the exception.** Rate-limit responses from SlowAPI typically use an `error` key instead of `detail`. Read both keys when logging.
</Note>

## Status code matrix

| Status | When to expect it                                                            | What to do                                                                            |
| ------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `200`  | Single match completed (whether or not a CRN was found)                      | Read `matched_company_number`                                                         |
| `202`  | Batch accepted and queued                                                    | Poll status (or wait for `callback_url`), then fetch results                          |
| `401`  | Missing or invalid API key                                                   | Fix or rotate the key — see [Authentication](/company-matching/guides/authentication) |
| `404`  | Batch `job_id` unknown or not owned by this key's user                       | Check the id from the submit response                                                 |
| `409`  | Batch results requested before the job has started                           | Wait and poll status until `running`, `completed`, or `failed`                        |
| `422`  | Schema validation failed, batch larger than 1,000, or invalid `callback_url` | Fix the body; shrink the batch; use https for webhooks                                |
| `429`  | Match rate limit exceeded                                                    | Back off — see [Rate limits](/company-matching/guides/rate-limits)                    |
| `500`  | Unexpected server error during matching                                      | Retry with exponential backoff                                                        |
| `503`  | Matching engine not ready                                                    | Retry after a short delay                                                             |

## Retrying

Retry `429`, `500`, and `503` with exponential backoff:

```text theme={null}
attempt 1 → wait 2 s
attempt 2 → wait 4 s
attempt 3 → wait 8 s
attempt 4 → give up, surface the error
```

Add random jitter (0–500 ms) so concurrent clients do not synchronise retries.

<Warning>
  Do **not** auto-retry `401`, `404`, `409`, or `422` with the same payload. Fix the key, id, timing, or body first.
</Warning>

## Common scenarios

### `401` on every call

Almost always a missing `Authorization` header, a JWT instead of a `dm_live_…` key, or a revoked key.

### `422` on batch submit

Either a company object failed validation (for example empty `input_name`), the list exceeds **1,000** companies, or `callback_url` / `webhook_secret` failed validation.

### `409` on results

You called `GET /match/batch/{job_id}/results` while the job was still `queued`. Poll `GET /match/batch/{job_id}` until status is `running`, `completed`, or `failed`, then fetch results.

### Client timeout on `POST /match`

Matching can take tens of seconds on a cold path. Set the client timeout to at least **60–120 seconds** before treating the call as failed.