> ## 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 Instant Classification API returns, what it means, and what to do.

The Instant Classification API uses standard HTTP status codes. Error responses include a JSON body with a `detail` field describing what went wrong.

## Error envelope

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

The `detail` wording may change between releases — match on status codes in your error handling, not on the string.

<Warning>
  **`429` is the exception.** Rate-limit responses use an `error` key instead of `detail`:

  ```json theme={null}
  {
    "error": "Rate limit exceeded: 5 per 1 minute"
  }
  ```

  Read both keys when logging errors, or you'll record an empty message for every throttled request.
</Warning>

## Status code matrix

| Status | When to expect it                                                                                                                 | What to do                                                                                                                                        |
| ------ | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`  | Successful classification.                                                                                                        | Process the response body.                                                                                                                        |
| `400`  | Invalid request: bad JSON, empty body, rejected input, or wrong login credentials. Also returned for an inactive account.         | Read `detail`, fix your request, and retry.                                                                                                       |
| `401`  | No `Authorization` header, or the token is expired, malformed, or no longer identifies an account.                                | Get a new token from `/api/v1/login/access-token`. See [Authentication](/instant-classification/guides/authentication).                           |
| `402`  | Free-tier usage quota exceeded.                                                                                                   | Contact [support@thedatacity.com](mailto:support@thedatacity.com) for a paid plan. See [Rate limits](/instant-classification/guides/rate-limits). |
| `422`  | Request failed schema validation: `Text` over 1,000 characters, `Website` over 500, or Terms & Conditions not accepted on signup. | Read `detail` and adjust the request.                                                                                                             |
| `429`  | Rate limit exceeded, on classification or on the login endpoints.                                                                 | Back off and retry. See [Rate limits](/instant-classification/guides/rate-limits).                                                                |
| `500`  | Unexpected server error.                                                                                                          | Retry with exponential backoff. If persistent, contact [support@thedatacity.com](mailto:support@thedatacity.com).                                 |
| `502`  | The upstream classification engine returned an error.                                                                             | Retry after a short delay.                                                                                                                        |
| `503`  | Classification engine unreachable or timed out after server-side retries.                                                         | Retry after a longer delay (30+ seconds).                                                                                                         |
| `504`  | Rare. A timeout that surfaced outside the normal retry path.                                                                      | Treat it like `503`.                                                                                                                              |

<Note>
  Any credential problem is a `401`: no header, an expired token, a malformed one, or a token whose account no longer exists. Refresh on `401` and retry once.

  The API returned `403` for expired tokens until July 2026. If your client still keys on `403`, update it.
</Note>

## Retrying

Retry `429`, `500`, `502`, `503`, and `504` 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 don't synchronise retries.

<Warning>
  Do **not** auto-retry `400`, `402`, or `422`. The same request will fail the same way. For `401`, get a new token first: retrying with the same one keeps failing.
</Warning>

<Note>
  The API already retries the upstream engine up to four times before it gives up, so a `503` means several attempts have failed. Wait longer than you would for a `500`.
</Note>

## Common error scenarios

### Classification returns 400

The most likely cause is an empty request body. You must supply either `Text` or `Website` (not both):

```json theme={null}
{"Text": "Software development and consulting"}
```

```json theme={null}
{"Website": "https://example.com"}
```

`Text` is capped at 1,000 characters and `Website` at 500 characters. Exceeding either limit returns `422`.

### Classification returns 402

Your free-tier quota is exhausted. The free tier does not reset — contact [support@thedatacity.com](mailto:support@thedatacity.com) for a paid plan.

### Classification returns 502 or 503

The upstream classification engine is temporarily unavailable. This is usually transient. Wait 30 seconds and retry.

A timeout also arrives as `503`, because the API wraps timeouts in its own retry handling before returning. Don't wait for a `504`.

### Classification hangs, or your client times out

Each upstream attempt gets up to 30 seconds, and the API makes up to four attempts with 1s, 2s and 4s waits between them. A slow request can therefore run for **well over a minute** before it either succeeds or fails.

Set your client timeout to at least **120 seconds** on this endpoint. A short client timeout is the most common cause of failures that look like API errors but are actually the client giving up early.

<Snippet file="need-help.mdx" />