Error Codes

All AXON runtime errors (MCP, Decision API, OpenClaw) normalize to this structure:

{
  "code": "APPROVAL_REQUIRED",
  "message": "Payment escalated for human approval.",
  "recoverable": true,
  "suggested_action": "Approve in dashboard, then call check_approval_status to retrieve approval_token, then retry governed_fetch with approval_token.",
  "details": { "decision_id": "..." }
}

Policy Errors

REJECTED_POLICY

Deterministic mandate gate denied (route/path/metadata/policy constraints).


Recoverable	No
Action	Fix the mandate configuration or request parameters

REJECTED_LIQUIDITY

Daily or monthly budget exceeded.


Recoverable	Yes
Action	Wait for budget reset, increase limits, or top up the pocket (deposit to the pocket address, or allocate from vault on server-signed orgs)

VAULT_ALLOCATION_UNAVAILABLE

Returned by POST /v1/wallets/:id/fund and POST /v1/orgs/:id/transfers/fund when the target org is browser-signed. Vault allocation requires the server to sign on the vault’s behalf, which is only possible when the org runs in full (server-signed) mode. Browser-signed orgs hold the vault private key in the user’s browser and must deposit directly to the pocket address instead.

{
  "code": "VAULT_ALLOCATION_UNAVAILABLE",
  "message": "Vault allocation requires a server-signed org. This org is browser-signed; use Deposit to Wallet instead.",
  "recoverable": false,
  "details": {
    "signing_mode": "browser",
    "alternative": "external_deposit"
  }
}


HTTP Status	`400`
Recoverable	No (the org’s signing mode is fixed at bootstrap)
Action	Use Deposit to Wallet (external on-chain USDC transfer on Base) to top up the pocket directly

REJECTED_DUPLICATE

Idempotency key already exists.


Recoverable	Yes
Action	Reuse the prior result — avoid replaying the same spend

REJECTED_NETWORK

Network not allowed by mandate.


Recoverable	No
Action	Update mandate to include the required network

Approval Errors

APPROVAL_REQUIRED

Risk stage escalated to human approval.


Recoverable	Yes
Action	Approve in dashboard, then use `check_approval_status` or `wait_for_approval_resolution` to retrieve `approval_token`, then retry with the same URL, method, and body plus `approval_token`

APPROVAL_NOT_READY

Approval exists but is still pending or denied.


Recoverable	Yes
Action	Wait for operator action

APPROVAL_EXPIRED

Approval was not consumed before expiry.


Recoverable	Yes
Action	Submit a new request to create a fresh approval

APPROVAL_ALREADY_CONSUMED

Approval token has already been used.


Recoverable	No
Action	Submit a new request if needed

Auth and Surface Errors

UNAUTHENTICATED

No bearer credential was presented.


HTTP Status	`401`
Recoverable	No
Action	Send `Authorization: Bearer ...`

INVALID_API_KEY

The bearer was present but did not resolve to a valid static key, tenant key, or platform session.


HTTP Status	`401`
Recoverable	No
Action	Verify the operator key, tenant key, or session token

TOOL_NOT_AVAILABLE_IN_RUNTIME_SURFACE

A wallet-scoped runtime credential tried to call an operator-surface route or tool.


HTTP Status	`403`
Recoverable	No
Action	Move the workflow to `/v1/operator/mcp`, the dashboard, or the operator CLI

TOOL_NOT_AVAILABLE_IN_OPERATOR_SURFACE

A runtime-only MCP tool was invoked on the operator surface.


MCP Surface	Operator MCP
Recoverable	No
Action	Retry on the runtime surface (`/v1/mcp` or stdio runtime)

WALLET_BINDING_REQUIRED

The caller reached a wallet-aware runtime surface without a wallet binding.


HTTP Status	`400`
Recoverable	Yes
Action	Use a wallet-bound tenant key, pass `wallet_id` where allowed, or configure `AGENT_WALLET_ID` for local fallback paths

Provider Errors

PROVIDER_UNVERIFIED

Provider registry entry missing or attestation mismatch.


Recoverable	No
Action	Fix registry entry (host/path/network/asset/payee)

Rate & Circuit Errors

RETRY_BUDGET_EXCEEDED

Task/host exceeded max_402_retries_per_task_host.


Recoverable	Yes
Action	Stop automation loop for that task/host

RATE_LIMITED

Request-rate or spend-rate gate triggered.


Recoverable	Yes
Action	Back off and retry later

CIRCUIT_OPEN

Host-level circuit breaker is open after repeated failures.


Recoverable	Yes
Action	Wait for circuit breaker cooldown

Scoring Errors

INTENT_MISMATCH

Risk stage flagged intent/category mismatch at escalation threshold.


Recoverable	No
Action	Review and correct the intent or category

ABSTAIN

Provider-search MCP tool wrapper error. The backend abstained instead of returning eligible offers.


Surface	HTTP runtime MCP provider-search tools
Recoverable	No
Action	Adjust the query, wallet, or eligibility constraints

Transport Errors

REQUEST_TIMEOUT

Upstream fetch timed out.


Recoverable	Yes
Action	Retry with longer timeout or check provider health

PAYMENT_FAILED

x402 challenge parse or signing failure.


Recoverable	Yes
Action	Retry — may be transient

SETTLEMENT_FAILED

Provider returned 402 even after signed payment payload.


Recoverable	Yes
Action	Retry — check provider health

INTERNAL_ERROR

Unexpected runtime failure.


Recoverable	Varies
Action	Check daemon logs

REST-Only Errors

VALIDATION_ERROR

Request body or route parameters are missing required fields or have invalid values.

NOT_FOUND

Requested resource does not exist.

HTTP and MCP behavior

400: validation failures, WALLET_BINDING_REQUIRED, and some recoverable route errors
401: UNAUTHENTICATED or INVALID_API_KEY
403: policy failures and capability-surface mismatches
404: NOT_FOUND
409: approval or idempotency conflicts
429: rate limiting / retry budgets
500: internal failure
502 / 503 / 504: selected upstream, circuit-breaker, and timeout failures

Malformed JSON is the one shape exception: the Decision daemon returns a JSON-RPC parse envelope with error.code = -32700 so REST and MCP callers see the same parse-failure contract. Cross-surface HTTP MCP failures are framed as JSON-RPC errors with the canonical AXON envelope in error.data.

Warning Codes

Successful or escalated decisions can include warnings instead of top-level errors:

Code	Meaning
`PROVIDER_UNVERIFIED_SOFT`	Provider not in registry (soft mode)
`LOW_ON_CHAIN_BALANCE`	Wallet balance is getting low
`LOW_ALIGNMENT_SCORE`	Intent alignment score below threshold
`INTENT_DOMAIN_DIVERGENCE`	Intent does not match the target domain

Troubleshooting Quick Map

Error	Fix
`APPROVAL_REQUIRED`	Perform the approval flow, then retry with `approval_token`
`PROVIDER_UNVERIFIED`	Fix registry entry
`RETRY_BUDGET_EXCEEDED`	Stop the automation loop for that task/host
`REJECTED_DUPLICATE`	Inspect the prior transaction or decision for the same idempotency key
`REQUEST_TIMEOUT` / `CIRCUIT_OPEN`	Back off and retry later
`TOOL_NOT_AVAILABLE_IN_RUNTIME_SURFACE`	Move the workflow to the operator surface
`WALLET_BINDING_REQUIRED`	Use a wallet-bound key or provide the required `wallet_id`

​Policy Errors

​REJECTED_POLICY

​REJECTED_LIQUIDITY

​VAULT_ALLOCATION_UNAVAILABLE

​REJECTED_DUPLICATE

​REJECTED_NETWORK

​Approval Errors

​APPROVAL_REQUIRED

​APPROVAL_NOT_READY

​APPROVAL_EXPIRED

​APPROVAL_ALREADY_CONSUMED

​Auth and Surface Errors

​UNAUTHENTICATED

​INVALID_API_KEY

​TOOL_NOT_AVAILABLE_IN_RUNTIME_SURFACE

​TOOL_NOT_AVAILABLE_IN_OPERATOR_SURFACE

​WALLET_BINDING_REQUIRED

​Provider Errors

​PROVIDER_UNVERIFIED

​Rate & Circuit Errors

​RETRY_BUDGET_EXCEEDED

​RATE_LIMITED

​CIRCUIT_OPEN

​Scoring Errors

​INTENT_MISMATCH

​ABSTAIN

​Transport Errors

​REQUEST_TIMEOUT

​PAYMENT_FAILED

​SETTLEMENT_FAILED

​INTERNAL_ERROR

​REST-Only Errors

​VALIDATION_ERROR

​NOT_FOUND

​HTTP and MCP behavior

​Warning Codes

​Troubleshooting Quick Map