> ## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.