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

# Errors

> Understand Clay Public API error responses.

Non-2xx responses return a JSON object with a human-readable `message`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "message": "Validation failed"
}
```

Use the HTTP status code as the machine-readable error category. Error response bodies do not currently include stable error codes.

## Recommended handling

* Treat `401` and `403` as authentication or authorization failures.
* Treat `404` as a missing resource or unavailable endpoint.
* Treat `409` and `422` as request state or validation problems.
* Treat `429` as rate limiting and retry after backing off.
* Treat `5xx` as transient server errors and retry with exponential backoff when the request is safe to retry.

For async endpoints, a `202` response means the job is still running. Poll the result endpoint until it returns a terminal `200` response.