REST API

Errors and limits

Agent distinguishes transport errors (HTTP codes on the request) from processing errors (the failed status with a human-readable error).

HTTP codes

Code	When
`401`	The token is missing, invalid, expired or blacklisted.
`403`	The task belongs to another user.
`404`	Task not found.
`409`	`POST /tool-results` or `POST /cancel` on a task that isn't in the `interrupted` status.
`422`	The request body failed validation.
`429`	The active task limit is exceeded.

422 — validation

{ "message": "…", "errors": { "input": ["The input field is required."] } }

429 — task limit

{ "message": "Too many active tasks. Maximum 5 concurrent tasks allowed." }

Active task limit

A user can have at most 5 active tasks at a time — in the pending, processing or interrupted statuses. The check and the creation are atomic (a per-user Redis lock), so parallel requests can't race past it. Wait for some tasks to reach a terminal status, or retry later.

A task in interrupted will never reach a terminal status on its own: it waits for your answer and holds a slot. GET /api/tasks?status=interrupted shows exactly what's taking up the limit; from there, either answer or free the slot by canceling (POST /api/tasks/{uuid}/cancel, or all at once with POST /api/tasks/cancel-interrupted).

Processing errors (status: failed)

If a task fails during processing, the HTTP request that created it still succeeded, but the status becomes failed and the reason goes into error. Raw Aist Backend response bodies never end up in error — only human-readable messages.

`error`	Reason
`Assistant is not available`	The assistant is unavailable (404 from Aist Backend when creating the chat/turn).
`Insufficient balance`	Not enough balance (402 from Aist Backend).
`Context window is full (~N tokens, the model fits M): …`	The history in `turns` plus the task doesn't fit into the model's context window. Agent doesn't compact the context on its own: drop older turns from `turns` or start a new conversation. If the history alone doesn't fit, the model isn't called at all.
`Token revoked`	The token was revoked while the task was being processed.

Acceptance timeout

If Aist Core doesn't confirm it has accepted the task within 30 seconds (no processing webhook arrives), the scheduler automatically moves the task to failed. This protects against “stuck” tasks.