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:
| Code | HTTP status | What to do |
|---|---|---|
invalid_request | 400 | Check the request against the exact tool schema or endpoint contract. |
api_key_required | 401 | Supply the server-held key using the endpoint's documented header. |
invalid_api_key | 401 | Check the key's current authority and binding. Never print the key or automatically switch credentials. |
permission_denied | 403 | The key lacks the required permission. Have an administrator review it. |
management_key_required | 403 | Use an unbound Embedded management key with the required permission, on the server only. |
subject_not_authorized | 403 | Resolve the correct user from your verified server session; do not change users to bypass denial. |
idempotency_conflict | 409 | The 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.