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

> All error responses share the same JSON envelope. HTTP status codes follow standard conventions.

The Data City API uses standard HTTP status codes. Every error response shares a single JSON envelope.

## Error envelope

```json theme={null}
{
  "message": "Human-readable description of what went wrong."
}
```

The `message` field is intended for log lines and developer diagnostics. Don't surface it verbatim to end users — phrasing may change between releases.

## Status code matrix

| Status | When to expect it                                                                             | What to do                                                                                                        |
| ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `200`  | Successful request.                                                                           | Process the response body.                                                                                        |
| `400`  | Malformed input (bad JSON, invalid query parameter, validation failed).                       | Inspect `message` and fix the request.                                                                            |
| `401`  | Missing or invalid Bearer token.                                                              | Re-check the `Authorization` header. See [Authentication](/api-reference/guides/authentication).                  |
| `403`  | Token is valid but lacks the required ability for the endpoint.                               | Email support to widen the token's scope.                                                                         |
| `404`  | The resource (company, list, set) does not exist.                                             | Confirm the identifier; some IDs expire after 24 hours — see [Batching](/api-reference/guides/batching).          |
| `422`  | Request well-formed but semantically invalid (for example, mutually exclusive filter fields). | Inspect `message`, adjust the body.                                                                               |
| `429`  | Too many requests.                                                                            | Back off and retry. See [Rate limits](/api-reference/guides/rate-limits).                                         |
| `500`  | Unexpected server error.                                                                      | Retry with exponential backoff; if persistent, contact [support@thedatacity.com](mailto:support@thedatacity.com). |
| `503`  | Service unavailable, usually during a deploy.                                                 | Retry after a short delay.                                                                                        |

## Retrying

Retry `429`, `500`, `502`, `503`, and `504` with exponential backoff. Do **not** auto-retry `400`, `401`, `403`, `404`, or `422` — the request will fail again the same way.

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