> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goclicks.ai/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>