Errors

All errors follow a consistent JSON shape:

{
  "error": {
    "code": "snake_case_error_code",
    "message": "Human-readable description.",
    "details": {}
  }
}

The details object is present only on validation errors and contains field-level information.

HTTP Status Codes

HTTP	Meaning	Retry?
`400`	Validation error or bad request body	Fix the request — do not retry
`401`	Missing or invalid API key / JWT	Re-authenticate, then retry
`402`	Insufficient credits	Show buy-credits prompt
`403`	Valid credentials, missing permission or scope	Check key scopes or agent `api_enabled`
`404`	Resource not found	Do not retry
`409`	Conflict — duplicate idempotency key or wrong execution state	Use a new idempotency key
`422`	Semantic validation failure (agent config invalid, schema mismatch)	Fix the request
`429`	Rate limit exceeded	Back off using `Retry-After` header
`500`	Internal server error	Retry with exponential backoff. Credits auto-refunded.

Common Error Codes

Code	HTTP	Cause
`unauthorized`	401	JWT expired or invalid API key
`forbidden`	403	Agent `api_enabled` is off, or key lacks the required scope
`payment_required`	402	Credit balance depleted
`rate_limit_requests_exceeded`	429	Request rate limit hit
`rate_limit_tokens_exceeded`	429	Token rate limit hit
`agent_not_found`	404	Agent ID does not exist or is not published
`workspace_not_found`	404	Workspace ID invalid or not found
`message_required`	400	Agent requires a `message` but none was sent
`external_auth_not_enabled`	403	Token exchange disabled for this workspace
`execution_not_resumable`	409	Execution is not in a paused state
`idempotency_conflict`	409	Idempotency key already used
`token_limit_exceeded`	402	Execution hit the token budget cap
`cost_limit_exceeded`	402	Execution hit the cost budget cap
`external_service_error`	500	LLM provider returned an error

Handling 429 Responses

Always check the Retry-After header before retrying:

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "error": {
    "code": "rate_limit_requests_exceeded",
    "message": "Rate limit exceeded. Retry after 12 seconds."
  }
}

See Rate Limits for per-agent and per-workspace limit values.

Handling 401 Responses

A 401 on an eak_ key means the key has expired. Re-authenticate:

Call POST /auth/external/{workspace_id} with a fresh provider JWT.
Store the new eak_ key and expires_at.
Retry the failed request.

Execution Failures and Credits

When an execution fails after credits are pre-deducted:

Pre-deducted credits are automatically refunded.
The error SSE event carries the failure reason.
The execution record’s status is set to Failed.

There is no need to request a manual refund for execution errors.

Rate Limits — limit values and tier breakdown
Authentication — key types and re-auth flow
Error Codes (API Reference) — complete error catalog