Skip to main content
This page covers the x402 API. V2 API errors are listed inline on each endpoint page (see POST /v2/check-address and POST /v2/screen). All error responses follow the same JSON shape: 
{
  "error": {
    "code":    "<machine-readable slug>",
    "message": "<human-readable explanation>"
  }
}

​
402 — Payment Required

The expected response on every paid endpoint until you supply a valid X-PAYMENT header. See Authentication for how to read the payment-required quote.
codeMeaning
payment_requiredFirst-call default — no proof was sent
payment_invalidX-PAYMENT was present but failed signature verification
payment_expiredThe signed quote’s validBefore is in the past
payment_replayedSame (payer, nonce) already settled — sign a fresh nonce
payment_underpaidSigned amount less than the quote’s amount
The payment-required header always accompanies a 402 with a fresh quote, so a client can re-sign without re-fetching.

​
400 — Bad Request

codeMeaning
chain_unsupported{chain} is not in the networks list
address_invalid{address} doesn’t match the expected format for the chain (EVM 0x + 40 hex, TRON base58, etc.)
body_invalidReserved (no current paid endpoint takes a body)

​
429 — Rate limited

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded: 60 per 1 minute"
  }
}
60 paid calls/minute per IP. Defense in depth on top of the cost of x402 itself. Behind a NAT? We’re working on per-payer rate- limiting; for now, contact us if it’s blocking a legitimate workload.

​
500 — Aegis-side failure (post-payment)

{
  "error": {
    "code": "aegis_internal_error",
    "message": "..."
  }
}
Payment was settled but our backend errored. Rare; logged to our audit channel. We don’t auto-refund — but if you see a 500 after a confirmed tx_hash on Basescan, contact support with the tx_hash and we’ll credit you back.

​
502 — Aegis backend unavailable

{ "error": { "code": "backend_unavailable", "message": "..." } }
The Aegis engine (or a required upstream RPC) was temporarily unreachable after payment. On the V2 ledger path this auto-refunds; on x402 see the 500 note above for the credit-back flow.