Retries and recovery
Handle interrupted x402 evaluations and model calls without authorizing an unnecessary second payment.
Keep the request body and PAYMENT-SIGNATURE until you receive both a successful result and a successful PAYMENT-RESPONSE. If a request is interrupted, first check the authorization or transaction status before signing another payment.
Recovery of a recently completed call is best-effort and time-limited. An immediate retry with the same body and signature may return the same result, but the API is not a durable store for evaluation or generation responses. Save every successful result and payment receipt in your own application.
Response handling
| Response | Action |
|---|---|
400, invalid_request / invalid_model | Correct the input or choose a current model before obtaining payment. |
400, invalid_payment | Check your client's payment-header encoding. |
413 | Reduce the request body. The error body may be plain text. |
402 without a signed request | Review and sign the returned x402 offer. |
402, payment_failed | Inspect the PAYMENT-RESPONSE receipt and wallet state before signing again. |
409, request_processing | The same payment is currently being processed by this instance; retry shortly with the same body and signature. |
409, payment_reused | Do not reuse that signature with a different body. |
502, generation_failed | Evaluation or generation failed. No settlement was requested; retry the same signed request while its authorization remains valid. |
503, verification_unavailable | Retry the same signed request after the facilitator recovers. |
503, settlement_unavailable | Settlement may be uncertain. Check the authorization and chain state before retrying or signing again. |
503, catalog_unavailable | Wait for current model pricing before requesting a new payment offer. |
503, service_unavailable | The gateway is not configured or is temporarily disabled. |
| Timeout or lost connection | Check payment status before creating a new authorization. |
If settlement succeeds but the result is lost and cannot be recovered, contact support with the payer address, route, model, approximate call time, and transaction hash. Never send a private key or seed phrase.
Browser playground
The playground saves an in-progress signed request in the current tab's session storage. Retry saved request resends the original route, body, and signature without asking for another wallet approval. Keep the tab open until the result and payment receipt are both displayed.