Errors & retries

Error codes, retries and idempotency.

Set up with your AI assistant

App

Where you use Claude Code

Paste the prompt into Claude Code. It includes setup steps and a read-only connection check.

Error shape

Error

{
  "request_id": "…",
  "status": "error",
  "data": null,
  "error": {
    "code": "task_busy",
    "message": "The task is still working…",
    "retryable": true
  }
}

HTTP	Codes	What to do
401	invalid_key, invalid_token, connection_revoked	Replace the key or reconnect the app.
403	insufficient_scope, key_budget_exceeded	Use the required permission or lower the task’s credit budget to the key cap.
409	task_busy, answers_required, results_not_ready	Check the task, then act on its status.
409	idempotency_conflict	Use a new key for a different job.
422	invalid_input, invalid_fields, invalid_cursor	Fix the request.
429	rate_limited, key_rate_limited, agent_busy, message_limit_reached	Wait and retry (Retry-After).
503	agent_unavailable, submissions_disabled	Retry with backoff.

Retries

Send an idempotency_key with POST /tasks and reuse it on retry: you get the same task back instead of a second one. Retry only errors marked retryable, with backoff.