Error Reference

All error responses use a standard JSON envelope:

{
  "error": {
    "code": "snake_case_string",
    "message": "Human-readable message",
    "details": { ... },
    "timestamp": "2026-05-12T10:30:00Z",
    "trace_id": "uuid-v4"
  }
}

Always present: code, message, timestamp, trace_id. details is omitted unless the error includes structured context.

Build your error-handling logic on code — message text can change.

Summary Table

Category	Codes	HTTP
Validation	`validation_error`, `bad_request`, `invalid_json`, `invalid_query`, `invalid_storage_key`	400
Auth	`unauthorized`	401
Credits	`payment_required`	402
Authorization	`forbidden`	403
Not Found	`not_found`	404
Conflict	`conflict`, `request_in_progress`, `duplicate_request`	409
Rate Limit	`rate_limit_anonymous_abuse`, `rate_limit_requests_exceeded`, `rate_limit_tokens_exceeded`, `rate_limit_cost_exceeded`, `rate_limit`	429
Internal	`internal_error`, `database_error`, `serialization_error`	500
External	`external_service_error`	502
Unavailable	`service_unavailable`	503

400 — Validation

Code	Message	Notes
`validation_error`	`Validation error: <message>`	`details: { "field": "<name>" }`
`validation_error`	`Request validation failed`	`details: { "errors": { "<field>": [...] } }` — per-field arrays
`invalid_json`	`Invalid JSON in request body`	`details: { "error": "<rejection>" }`
`invalid_query`	`Invalid query parameters`	`details: { "error": "<rejection>" }`
`bad_request`	`MESSAGE_REQUIRED`	Agent execute — no user message
`bad_request`	`EMPTY_MESSAGE`	Whitespace-only message
`bad_request`	`client_tools_not_accepted: ...`	No AI node accepts client tools
`bad_request`	`too_many_client_tools: <N> exceeds limit of <M>`	Client tool count exceeded
`bad_request`	`client_tool_name_collision: '<name>' ...`	Tool name conflicts with server tool
`validation_error`	`invalid_tool_name: '<name>' must match ^[a-z][a-z0-9_]{0,63}$`	`field: "client_tools"`
`validation_error`	`payload size <N> bytes exceeds limit of <M> bytes`	`field: "variables"`. Default 16 KiB
`bad_request`	`Missing X-Workspace-Id header`	—
`bad_request`	`X-Workspace-Id must be a UUIDv7`	—
`bad_request`	`X-Workspace-Id contains invalid characters`	Only `[A-Za-z0-9_-]`
`invalid_storage_key`	`missing namespace: <key>`	—
`invalid_storage_key`	`unknown namespace: <ns>`	Only `attachments`, `media`, `thumbnails`

401 — Unauthorized

Code	Message	Notes
`unauthorized`	`Missing authorization header`	—
`unauthorized`	`Invalid token`	JWT verify failed
`unauthorized`	`Invalid or expired API key`	`wak_` or `eak_` key check failed
`unauthorized`	`Invalid credentials`	Login — wrong password
`unauthorized`	`Refresh token has been revoked`	Rotation/logout consumed
`unauthorized`	`Token verification failed: <error>`	Firebase JWT verify failed
`unauthorized`	`Missing webhook signature headers`	Fal.ai webhook
`unauthorized`	`Webhook timestamp expired`	Fal.ai — 5-min tolerance
`unauthorized`	`Invalid webhook token`	RevenueCat webhook

402 — Payment Required

Code	Message	Notes
`payment_required`	`insufficient_credits`	Credit balance depleted. No `details`.

403 — Forbidden

Code	Message	Notes
`forbidden`	`API key does not have agent:execute scope`	—
`forbidden`	`This agent does not allow API key access`	Enable `API Enabled` in agent settings
`forbidden`	`API key does not have access to this agent`	Agent allowlist mismatch
`forbidden`	`External auth not enabled`	Workspace feature flag off
`forbidden`	`Customer identity required`	Ephemeral key missing `external_customer_id`
`forbidden`	`Role '<Role>' cannot <action>`	Insufficient workspace role
`forbidden`	`RevenueCat webhook secret not configured`	Workspace setting missing

404 — Not Found

Code	Message
`not_found`	`Resource not found: Agent not found`
`not_found`	`Resource not found: Execution not found`
`not_found`	`Resource not found: Workspace not found`
`not_found`	`Resource not found: No checkpoint found for execution <id>`
`not_found`	`Resource not found: Conversation not found`
`not_found`	`Resource not found: Customer not found`
`not_found`	`Resource not found: No rate limit configured for this scope`

409 — Conflict

Code	Message	Notes
`conflict`	`execution_already_finished: cannot cancel execution in <status> state`	`details: { "status", "execution_id" }`
`conflict`	`execution_awaiting_client_tool: use /tool-result to fulfil`	Use the tool-result endpoint
`conflict`	`execution_terminal: cannot resume execution with status <status>`	Start a new turn
`conflict`	`tool_call_already_fulfilled: '<id>' has already been fulfilled`	—
`conflict`	`Email already in use`	—
`request_in_progress`	`A request with this Idempotency-Key is currently being processed`	—
`duplicate_request`	`Duplicate request: this Idempotency-Key has already been used`	—

429 — Rate Limit

The V2 rate limiter emits four granular codes. Key off code, not message text.

Code	Message	Details
`rate_limit_anonymous_abuse`	`Suspicious activity detected. Try again in <N> seconds.`	`{ "reset_in_seconds": N }` — no limit disclosed
`rate_limit_requests_exceeded`	`Request limit of <N> exceeded. Try again in <M> seconds.`	`{ "limit_type": "requests", "scope_type": "...", "limit": N, "reset_in_seconds": M }`
`rate_limit_tokens_exceeded`	`Token quota of <N> exceeded. Resets in <M> seconds.`	`{ "limit_type": "tokens", "scope_type": "...", "limit": N, "reset_in_seconds": M }`
`rate_limit_cost_exceeded`	`Spend cap reached. Resets in <N> seconds.`	`{ "limit_type": "cost", "scope_type": "...", "reset_in_seconds": N }` — limit omitted
`rate_limit`	`Rate limit exceeded. Try again in 60 seconds`	`{ "retry_after": N }` — login throttle, token exchange

scope_type values: agent, customer, user, workspace.

Headers on 429:

Header	Present for
`Retry-After: <seconds>`	Always
`X-RateLimit-Limit: <N>`	`requests` and `tokens` limit types only

SSE stream rate limit (different shape, emitted mid-stream):

{
  "error": "<message>",
  "code": "rate_limited",
  "retry_after_seconds": 30,
  "error_type": "rate_limited",
  "termination_reason": "failed"
}

Note: code: "rate_limited" (not rate_limit_*) is used only in SSE streams.

500 — Internal Error

Code	Message	Notes
`internal_error`	`An internal error occurred. Please try again later.`	Real cause logged only
`database_error`	`A database error occurred. Please try again later.`	MVCC conflicts — retry the request
`serialization_error`	`A serialization error occurred. Please try again later.`	—

502 — External Service Error

Code	Message
`external_service_error`	`An external service error occurred. Please try again later.`

Sources: LLM provider failures, Firebase JWKS fetch, Action node HTTP calls. The real upstream error is logged but not returned to clients.

503 — Service Unavailable

Code	Message	Cause
`service_unavailable`	`Credit service not configured`	Credits not enabled on workspace
`service_unavailable`	`Token exchange not configured`	External auth not enabled
`service_unavailable`	`File storage not configured`	S3 not configured on workspace

Special Cases

MISSING_WORKSPACE non-standard envelope — extractors.rs can return { "code": "bad_request", "message": "MISSING_WORKSPACE" } without timestamp/trace_id. Programming error — should not reach production.
WebSocket upgrades — raw status, no body — 401/403/503 from the WebSocket upgrade endpoint appear as connection failures in the browser with no JSON body.
SSE stream errors — use the "rate_limited" code (not rate_limit_*). Always check termination_reason.
database_error (500) MVCC — classified as expected internally. Retry once.

Rate Limits — scope hierarchy and limit configuration
REST Conventions — request / response conventions
Errors — error handling patterns and retry guidance