Reference
Errors and limits
Verify returns problems as invalidReason and settle as errorReason. The reason strings are the same across both.
Error reasons
| Reason | Meaning | Retry? |
|---|---|---|
| malformed_request | Body failed x402 v2 schema validation. The message names the failing field. | No, fix the request |
| unsupported_x402_version | Only x402Version 2 payloads are accepted. v1 requirements (maxAmountRequired) are rejected. | No |
| unsupported_network | Requirements must target eip155:5042 or eip155:5042002. | No |
| rate_limited | Too many requests from one IP on this endpoint. | Yes, after a minute |
| invalid_exact_evm_* | Signature, amount, recipient, validity window, nonce or balance check failed. The suffix says which. | No, get a new payment |
| unexpected_verify_error | RPC or facilitator problem during verify. | Yes |
| unexpected_settle_error | RPC or relayer problem during settle. Nothing was broadcast. | Yes |
HTTP status codes
| Status | When |
|---|---|
| 200 | The request was processed. Check isValid or success for the outcome; a rejected payment is still a 200. |
| 400 | malformed_request, unsupported_x402_version or unsupported_network. |
| 429 | rate_limited. |
| 500 | unexpected_verify_error or unexpected_settle_error. |
Rate limits and timeouts
Each of /verify and /settle allows 120 requests per minute per IP. Settlement waits up to 60 seconds for a receipt. Requirements should set maxTimeoutSeconds to at least the time your handler needs plus settlement; the Arcus merchant routes use 120.
Live network health is published at /health and on the status page.