Error codes

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.

`code`	Meaning
`payment_required`	First-call default — no proof was sent
`payment_invalid`	`X-PAYMENT` was present but failed signature verification
`payment_expired`	The signed quote’s `validBefore` is in the past
`payment_replayed`	Same `(payer, nonce)` already settled — sign a fresh nonce
`payment_underpaid`	Signed 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

`code`	Meaning
`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_invalid`	Reserved (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.

Get started

Authentication

x402 Endpoints (USDC pay-per-call)

V2 Public API

Webhooks (push events)

Methodology

Reference

Other

402 — Payment Required

400 — Bad Request

429 — Rate limited

500 — Aegis-side failure (post-payment)

502 — Aegis backend unavailable

​402 — Payment Required

​400 — Bad Request

​429 — Rate limited

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

​502 — Aegis backend unavailable

402 — Payment Required

400 — Bad Request

429 — Rate limited

500 — Aegis-side failure (post-payment)

502 — Aegis backend unavailable