# Errors

> Every error the Agent API returns, what it means, and what to do.

Errors are JSON with a stable `code` and a human-readable `message`:

```json
{ "error": { "code": "out_of_credits", "message": "You're out of Clatter Labs credits. ..." } }
```

| Status | `code` | Meaning | What to do |
| --- | --- | --- | --- |
| 400 | `bad_request` | Missing `input`, or a bad `tier` | Fix the request |
| 401 | `invalid_api_key` | The key is wrong or revoked | Check the key, or create a new one |
| 401 | `missing_account_id` | No `X-Clatter-Account` header | Send your Account ID |
| 401 | `account_mismatch` | The Account ID doesn't own this key | Use the key owner's Account ID |
| 402 | `out_of_credits` | Your credit balance is used up | See [Credits](/billing/credits) |
| 403 | `insufficient_scope` | The key lacks the permission | Create a key with that permission |
| 403 | `early_access` | Your account isn't in the early-access program yet | Ask for access |
| 403 | `no_cloud_account` | Your account hasn't been set up for Cosmos Agent | Sign in once to a Cosmos Agent app with this account, then retry. If it persists, visit the [Help Center](https://help.clatterlabs.com/agent-api/) |
| 403 | `account_suspended` | Your account is paused for 24 hours under the [Abuse policy](/policies/abuse) | Wait until `resets_at` (`Retry-After` seconds), or appeal through the [Help Center](https://help.clatterlabs.com/security-privacy/suspension/appeal-a-suspension) |
| 404 | `not_found` | No run with that id on your account | Check the id |
| 405 | `method_not_allowed` | Wrong HTTP method | See the endpoint's reference |
| 413 | `too_large` | `input`, `metadata` or the body is too big | See [Limits](/agent/limits) |
| 429 | `rate_limited` | Over the key's requests per minute | Wait `Retry-After` seconds |
| 429 | `too_many_runs` | 5 runs already in progress | Wait for one, or cancel one |
| 502 | `upstream` | Cosmos Cloud didn't answer | Retry with backoff |
| 503 | `unavailable` | The key couldn't be checked right now | Retry with backoff |

## Runs that fail

A run that starts but can't finish ends with `status: "failed"` and an `error`:

```json
"error": { "code": "out_of_credits", "message": "You're out of Clatter Labs credits." }
```

`code` is `out_of_credits` when the balance ran out midway, otherwise `run_failed`.

## Rate limit headers

Successful keyed responses carry `X-RateLimit-Limit` and `X-RateLimit-Remaining`. A `429` adds `Retry-After` (seconds).