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

# Errors

> Status codes and the error response format

## Error Format

Every non-success response returns the same JSON envelope:

```json theme={null}
{
  "error": "not_found",
  "message": "Lead not found"
}
```

* `error` — a stable, machine-readable code. Branch your integration logic on this.
* `message` — a human-readable explanation. Log it; don't parse it.

## Status Codes

| Status | `error`               | Meaning                                                          |
| ------ | --------------------- | ---------------------------------------------------------------- |
| `400`  | `invalid_id`          | The ID in the URL is not a valid UUID                            |
| `401`  | `missing_api_key`     | No `Authorization` header, or it isn't a `Bearer` token          |
| `401`  | `invalid_api_key`     | The key is unknown or has been revoked                           |
| `403`  | `api_access_disabled` | The key is valid, but API access is off for the organization     |
| `404`  | `not_found`           | No such record, or it belongs to another organization            |
| `429`  | —                     | Rate limit exceeded. Plain-text body with a `Retry-After` header |

## Handling Errors

* **`400`** — a bad ID. Check that you're passing the record's UUID and not a name or a URL.
* **`401`** — fix the credentials. Retrying won't help until the key is corrected or replaced.
* **`403`** — API access has been turned off for your organization. Contact [support@cortado.pro](mailto:support@cortado.pro).
* **`404`** — treat as "the record isn't available to this key". It may have been deleted, or it may belong to another organization.
* **`429`** — back off. Wait the seconds given in `Retry-After` (60) and retry.

<Tip>
  Retrying is only useful for `429` and for network or `5xx` failures. Retrying a `400`, `401`, `403`, or `404` produces the same result and only burns rate limit.
</Tip>