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 > 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.

Success codes

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

Status	Meaning
`200`	The request was accepted and work is under way or done. The body reflects the task at response time, not a settled turn: a new `POST /task` returns `status: "plan"` while planning runs in the background. Poll `GET /task/{task_id}/state` or subscribe to the stream until the task settles.
`202`	The request is queued behind the current turn. The body carries `status: "accepted"`; poll `GET /task/{task_id}/state` or subscribe to the stream.

Branch on the body’s status field, not on the status code. Neither code means the turn finished. POST /task and POST /task/start return 202 when task_id names an existing task. POST /task/{task_id}/continue and POST /task/{task_id}/execute return 202 unless wait is true.

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.
`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.

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

Retry

One turn at a time

Terminal errors

Streaming

​Success codes

​Codes

​Retry

​One turn at a time

​Terminal errors

​Streaming

Success codes

Codes

Retry

One turn at a time

Terminal errors

Streaming