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

# Errors

> Handle stable CREAO Developer API error codes.

## Error format

Developer API errors use stable machine-readable codes:

```json theme={null}
{ "error": "INVALID_INPUT" }
```

Some errors include additional structured fields, such as credit balances or retry timing. Do not depend on English error messages in production clients.

## Common codes

| HTTP status | Code                      | Meaning                                                                                                                                       |
| ----------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`       | `INVALID_INPUT`           | Invalid JSON, invalid UUID, unsupported status filter, invalid request shape, unknown field, empty patch body, or another validation failure. |
| `400`       | `INPUT_TOO_LARGE`         | Realtime run input is larger than the public request limit.                                                                                   |
| `401`       | `AUTHENTICATION_REQUIRED` | Account API key is missing, malformed, revoked, or unknown.                                                                                   |
| `402`       | `INSUFFICIENT_CREDITS`    | The account does not have enough credits to start the run.                                                                                    |
| `403`       | `ACCOUNT_BLOCKED`         | The account is blocked from running.                                                                                                          |
| `404`       | `AGENT_NOT_FOUND`         | The agent is missing, inactive, deleted, not personal, or outside the account boundary.                                                       |
| `404`       | `CONVERSATION_NOT_FOUND`  | The conversation is missing or outside the account boundary.                                                                                  |
| `404`       | `RUN_NOT_FOUND`           | The run is missing or outside the account boundary.                                                                                           |
| `429`       | `RATE_LIMITED`            | Account-level or IP-level rate limit exceeded.                                                                                                |
| `503`       | `SERVICE_UNAVAILABLE`     | Agent dispatch or Platform write path was unavailable before the request was accepted.                                                        |

Async `/v1/runs` reports oversized input as `INVALID_INPUT`. Realtime `/v1/realtime/runs` reports oversized input as `INPUT_TOO_LARGE` before the stream opens.

## Credit errors

Credit errors can include `available` and `required` values:

```json theme={null}
{
  "error": "INSUFFICIENT_CREDITS",
  "available": 0,
  "required": 1000
}
```

## Rate-limit errors

Rate-limit responses include a `Retry-After` header when a retry delay is available.

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 60
```

## Stream failures

For realtime runs, failures that happen before the stream opens return normal JSON errors. Failures after the stream opens are sent as terminal events:

```text theme={null}
event: run.failed
data: {"run_id":"11111111-1111-4111-8111-111111111111","status":"failed","error":{"code":"EXECUTION_FAILED"}}
```