Errors

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

{
  "error": "out_of_credits",
  "message": "Out of credits. Add credits at https://platform.autumn.ai (Settings > Billing), 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.

Success codes

Task routes return two success codes. Both bodies carry task_id.

Status	Meaning
`200`	The request was accepted or the requested turn finished synchronously. Use `state` and `done` to read the task lifecycle.
`202`	The request was accepted for background work, or a continue was queued behind a running turn. Use `state`, `done`, and `queue_position` to follow it.

Starting with POST /task or /task/start always returns immediately; their compatibility wait body field does not make a start request block. POST /task/{task_id}/continue and /execute also return immediately by default. Their legacy wait: true body option blocks for the turn. Use integer wait values as bounded timeouts only on the GET status routes.

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 and the operation could not queue. `/continue` normally queues and returns `202`; queueing may be unavailable. `/execute` is not queued while a turn runs.
`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.
`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.

Status reads

GET /task/{task_id}, /state, and /stream return 503 service_unavailable when Autumn cannot read task state. Retry the request; do not treat this response as task_not_found. A 404 task_not_found means the task is actually missing.

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. A continue submitted while it is running is queued and returns 202; if queueing is unavailable, the legacy 409 task_executing response is used. Execute is not queued while a turn is running. Serialize writes per task_id; use GET /task/{task_id}?wait=50 or the status stream to follow the current turn.

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.

Streaming

After an SSE stream opens, a failure arrives as a beanstalk_error event, not an HTTP status. See Live messages.

Reference

Endpoints

Success codes

Codes

Status reads

Retry

One turn at a time

Terminal errors

Streaming

​Success codes

​Codes

​Status reads

​Retry

​One turn at a time

​Terminal errors

​Streaming

Success codes

Codes

Status reads

Retry

One turn at a time

Terminal errors

Streaming