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

> ## Agent Instructions
> Autumn AI (autumn.ai) is a people and company intelligence API, a separate company from useautumn.com (billing software); no billing-product routes exist here.
> Base URL https://api.autumn.ai. Auth on every request: `X-API-Key: <key>` or `Authorization: Bearer <key>`. Plain HTTP + JSON. Schemas: https://www.autumn.ai/docs/openapi.json. Every docs page is Markdown at its URL plus `.md`.

# Errors

> One error body. Branch on `error`. Retry when `retryable` is true.

Every error has the same body. Branch on `error`. Show `message` to a person.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": "out_of_credits",
  "message": "Out of credits. Add credits at https://platform.autumn.ai (Settings > Usage), then send the request again. Retrying without credits fails the same way.",
  "retryable": false,
  "resolve": "https://platform.autumn.ai",
  "request_id": "req_3f9c2a1b0d4e5f6a7b8c"
}
```

| Field                     | When         | Meaning                                                                                                                                   |
| ------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `error`                   | always       | Stable `snake_case` code. It does not change between releases.                                                                            |
| `message`                 | always       | What went wrong and what to do next.                                                                                                      |
| `retryable`               | always       | `true`: the same request can succeed later. `false`: change the request, key, balance or id first.                                        |
| `request_id`              | always       | Also the `X-Request-ID` header. A client-sent `X-Request-ID` (1-64 characters from `A-Z a-z 0-9 _ . : -`) is echoed. Quote it to support. |
| `retry_after`             | `429`, `503` | Seconds to wait. Also the `Retry-After` header.                                                                                           |
| `resolve`                 | `402`        | Where to fix the cause.                                                                                                                   |
| `param`, `detail`         | `422`        | The field that failed validation, and the validator output.                                                                               |
| `task_id`, `task_created` | some `4xx`   | The task the error refers to. `task_created: false` on a refused `POST /task`: no task exists.                                            |

## Codes

| Status       | `error`                                                  | `retryable` | What to do                                                                                                                           |
| ------------ | -------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `400`, `422` | `invalid_request`                                        | no          | `422`: a field failed validation. Fix the field in `param`. `400`: the body is valid but Autumn rejects it. Read `message`.          |
| `401`        | `unauthorized`                                           | no          | Send the full key as `X-API-Key` or `Authorization: Bearer`. The response carries `WWW-Authenticate`.                                |
| `402`        | `out_of_credits`                                         | no          | Add credits at `resolve`, then send the request again.                                                                               |
| `404`        | `task_not_found`                                         | no          | Check the `task_id`, or list tasks with `GET /task`.                                                                                 |
| `404`        | `not_found`                                              | no          | The route does not exist. `message` points at the route list.                                                                        |
| `405`        | `method_not_allowed`                                     | no          | Wrong HTTP method for the route. Check the method in the OpenAPI spec.                                                               |
| `413`        | `payload_too_large`                                      | no          | Send large inputs through `POST /upload-url`.                                                                                        |
| `415`        | `unsupported_media_type`                                 | no          | Send the body as JSON with `Content-Type: application/json`.                                                                         |
| `409`        | `task_executing`                                         | yes         | A turn is running. Poll `GET /task/{task_id}/state` until `active` is false, then send again. Stop only to abandon the turn.         |
| `409`        | `task_in_cron_mode`                                      | no          | The task runs on a schedule. Switch it to chat mode in the platform, or start a new task.                                            |
| `409`        | `task_exists`                                            | no          | A task with that `task_id` exists. Continue it with `POST /task/{task_id}/continue`.                                                 |
| `429`        | `rate_limited`                                           | yes         | Wait `retry_after` seconds. See [Rate limits](/docs/api/rate-limits).                                                                     |
| `500`        | `internal_error`                                         | yes         | If the body carries `task_id`, the task exists: continue it. Otherwise send again. If it repeats, contact support with `request_id`. |
| `502`        | `bad_gateway`                                            | yes         | An upstream service failed. Send the request again shortly.                                                                          |
| `503`        | `service_unavailable`, `at_capacity`, `auth_unavailable` | yes         | Wait `retry_after` seconds, then send the request again.                                                                             |

## Retry

Read `retryable`. Do not infer it from the status.

* `true`: wait `retry_after` seconds when present, else a short backoff, then send the same request again.
* `false`: the same request fails the same way. Change the request, key, balance or id first.

## One turn at a time

A task runs one turn at a time. `409 task_executing` on continue or execute: poll state until the turn ends, then send again. Serialize calls per `task_id`. Do not stop a turn to get a message through; stop abandons its work.

## Terminal errors

`402 out_of_credits` on continue or execute means the turn did not start. The task stays in `plan` and does not resume when credits arrive: add credits, then send the request again. See [Task lifecycle](/docs/concepts/lifecycle).

## Streaming

After an SSE stream opens, a failure arrives as a `beanstalk_error` event, not an HTTP status. See [Live messages](/docs/guides/streaming).