> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axon402.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Complete error reference for the AXON runtime

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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.