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

# Errors and retries

> Every status the API returns and what to do about it.

## Error body

Failures return `{"detail": "<reason>"}`. Request validation is the exception: a schema violation returns `422` with a body that lists each issue in FastAPI's format:

```json 422 validation shape theme={null}
{
  "detail": [
    {
      "type": "string_too_long",
      "loc": ["body", "name"],
      "msg": "String should have at most 200 characters"
    }
  ]
}
```

## Status codes

| Status | When | Detail | Retry? |
| - | - | - | - |
| `401` | No key in the Authorization or X-API-Key header | `Missing API key` | No — fix auth |
| `401` | Unknown or disabled key | `Invalid API key` | No — check the key's state in the app |
| `403` | Body template\_id ≠ the key's agent | `API key is not valid for the requested template` | No |
| `404` | The key's agent was deleted, or the run ID is unknown, in another org, or another agent's | `Agent template not found` · `Agent not found` | No |
| `409` | The agent is archived | `(archived-template message)` | No — unarchive it in the app |
| `413` | Decoded files total over 10 MiB | `total file size exceeds the allowed limit` | No — shrink the payload |
| `422` | A file is not valid base64 | `file '<name>' is not valid base64` | No |
| `422` | The organization has no usable inference model | `(allowlist message)` | No — fix the organization's model configuration in the app |
| `422` | Schema validation (name length, >10 files, missing fields, bad UUID) | `FastAPI validation array` | No |
| `502` | Event-history lookup failed (GET only) | `event history lookup failed` | Yes — with backoff |
| `503` | Event history temporarily unavailable (GET only) | `event history is temporarily unavailable` | Yes — with backoff |

## Retry guidance

Because `GET /v1/agents/{agent_id}` is read-only, you can retry it freely. If it returns `502` or `503`, back off exponentially (1s, 2s, 4s, up to about 30s) and keep polling.

A `404` usually means you're using the wrong key for the agent you're querying. IDs from other organizations or agents also return `404`, the same response as a nonexistent ID.

<Warning>
  **Don't automatically retry POST /v1/agents.** This endpoint doesn't support idempotency keys, so retrying a create request starts a second
  run. Only retry a create if you received no HTTP response at all, and reconcile what
  actually ran afterwards.
</Warning>


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