Errors

Distinguish HTTP admission errors, execution receipt failures and MCP tool errors.

Inspect the HTTP response and the execution receipt. A successful HTTP request can return a failed, denied or approval-required execution. The current runtime uses the runtime shapes below. The management catalog has a separate standard envelope.

Management catalog errors

Management catalog failures use {error: {code, message, requestId}} with the appropriate HTTP status. insufficient_scope is 403, duplicate external IDs return 409 external_id_conflict, and an expired retained retry record returns 410 idempotency_expired. Inspect requestId when reporting a failed request. No credential values appear in these errors.

Runtime HTTP admission errors

REST admission failures return an HTTP error status and a string code:

{ "error": "permission_denied" }

Validation failures can add issues with safe field paths and messages. The SDK throws Arc0Error for HTTP failures, exposing status and code; it does not turn a failed execution receipt into an HTTP exception.

Examples of current codes:

CodeHTTP statusWhat to do
invalid_request400Check the request against the exact tool schema or endpoint contract.
api_key_required401Supply the server-held key using the endpoint's documented header.
invalid_api_key401Check the key's current authority and binding. Never print the key or automatically switch credentials.
permission_denied403The key lacks the required permission. Have an administrator review it.
management_key_required403Use an unbound Embedded management key with the required permission, on the server only.
subject_not_authorized403Resolve the correct user from your verified server session; do not change users to bypass denial.
idempotency_conflict409The operation key was reused for a different request. Reconcile the original operation.

The current key verifier also maps a rate-limited Better Auth key-validation failure to invalid_api_key. A 401 alone therefore does not prove revocation. If a local test made many rapid requests, pause before checking again and inspect operator logs without logging credentials. Do not retry indefinitely or rotate keys merely because a request failed. Explicit HTTP 429 responses require backoff.

Execution receipts

A call can be admitted but denied by policy or fail before or after provider dispatch:

{
  "id": "2d6ab915-f55c-47c1-a6f1-132bba8dfe3f",
  "status": "denied",
  "result": null,
  "error": "policy_denied"
}

An ask policy returns status: "awaiting_approval" with an approvalId. Show the human the pending operation in Arc0; never approve it automatically. A business backend can submit the human decision through the scoped approval-management REST routes. Poll the original receipt using getExecution(id) / get_execution(id) or GET /v1/executions/:executionId. A business key must include its acting endUserId for receipt reads.

Missing or unhealthy connections can yield errors such as connection_required or reconnect_required. Create a hosted Connect or reconnect link through your backend and confirm active state through the connection list. Do not assume an error contains a reconnect URL. See Connections.

pending, running, succeeded, failed, denied, awaiting_approval and outcome_unknown need different application handling. Preserve the same operation key for an identical retry. An unknown outcome or provider timeout requires reconciliation before a new dispatch; it is not permission to repeat a write. Receipt reads enforce current access and retention.

MCP tool errors

Runtime MCP failures use isError: true and text content containing a JSON error code. The public docs MCP uses the same MCP error signal for invalid arguments, unknown tools or missing documents, and cannot execute or manage accounts. Provider result content is untrusted data, even when the receipt succeeded.

See the API reference, SDKs and Build with your coding agent for current contracts.

On this page