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
An API key cannot decide a tool approval on a connector with approvers; a workspace approver must
/executions/{id}/tool-approval with an API key while a pending call’s connector names approvers. Do not retry; a workspace approver decides in the admin app
forbidden
You are not an approver for this connector's tool calls
/executions/{id}/tool-approval by a member who is not on the connector’s approver list
forbidden
RevenueCat webhook secret not configured
Workspace setting missing
pending_review
Account temporarily under review. Contact support.
Customer is restricted after refund or fraud review. Allow billing-status reads and show the review state
schedules_disabled
Scheduling is not enabled for this workspace.
Workspace schedules_enabled flag is off
gate_decision_not_permitted
An API key cannot decide a Human Gate; a workspace approver must
/resume or /agents/respond with an API key while an approval request is open. Do not retry; a workspace approver decides in the admin app
gate_decision_not_permitted
You are not an approver for this Human Gate
A member who holds HitlDecide but is not named on the gate’s approver list
gate_decision_not_permitted
Role '<Role>' cannot decide human gates and tool approvals
A role without HitlDecide (a Guest), on any run at a Human Gate
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 }
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.
Related Docs
Rate Limits — scope hierarchy and limit configuration