Error Codes

Error Response Format

All API errors include a request_id field that can be provided to support for debugging.

{
  "error": {
    "type": "policy_violation",
    "message": "Daily limit of $500 exceeded",
    "details": { ... },
    "request_id": "req_abc123"
  }
}

PolicyViolationError

HTTP 403 Forbidden

The transaction was blocked by the wallet spending policy.

Common Causes

• Amount exceeds per-transaction, daily, or monthly limit
• Merchant or category is on the block list
• Transaction attempted outside allowed time window

Resolution

• Check the wallet policy with GET /api/v2/wallets/{id}
• Lower the transaction amount or update the policy
• Add the merchant to the allowlist if appropriate

ComplianceDenied

HTTP 403 Forbidden

The transaction was blocked by compliance screening (KYA, sanctions, or AML).

Common Causes

• Recipient address flagged by sanctions screening (Elliptic)
• Agent trust score below minimum threshold
• KYA verification incomplete or expired

Resolution

• Check the agent trust score with GET /api/v2/wallets/{id}/trust-score
• Complete KYA verification if pending
• Contact support if you believe this is a false positive

InsufficientFunds

HTTP 402 Payment Required

The wallet does not have enough balance to cover the transaction.

Common Causes

• Wallet balance is lower than the requested amount
• Balance is locked by an existing hold
• Gas fees are not covered

Resolution

• Check balance with GET /api/v2/wallets/{id}/balances
• Fund the wallet with the required token
• Release any unnecessary holds

NoRoute

HTTP 422 Unprocessable Entity

No valid route found to execute the transaction on the specified chain.

Common Causes

• The token is not supported on the specified chain
• The chain is not configured or temporarily unavailable
• RPC endpoint is unreachable

Resolution

• Check supported chains and tokens in the documentation
• Verify the chain parameter is correct (e.g., "base" not "Base")
• Try a different chain that supports your token

AllAdaptersExhausted

HTTP 502 Bad Gateway

All chain adapters failed to execute the transaction.

Common Causes

• All RPC providers are down or rate-limited
• Network congestion causing timeouts
• Smart contract execution reverted on all attempts

Resolution

• Retry after a short delay (the system retries automatically up to 3 times)
• Check network status at status.sardis.sh
• If persistent, contact support with the request_id from the error response