B402 has two error layers:
- HTTP/gateway or B402 envelope errors: authentication, malformed requests, merchant state, rate limits, or infrastructure failures.
- x402 business outcomes: Verify and Settle return HTTP 200 with details inside
data.
Web3 Gateway Errors
| HTTP | Code | Meaning |
|---|---|---|
| 400 | 40001 | Invalid request parameters |
| 401 | 40101 | Missing, invalid, deleted, or disabled API Key |
| 401 | 40102 | Missing or invalid request signature |
| 401 | 40103 | Expired timestamp or replayed request |
| 403 | 40104 | API Key access policy rejected the request: check B402 Payments permission, IP whitelist, and endpoint allowlist |
| 429 | 42900 | Gateway rate limit exceeded |
| 500 | 50000 | Internal gateway error |
| 503 | 50001 | Service temporarily unavailable |
B402 Envelope Errors
| Code | Meaning |
|---|---|
1160101 | System error |
1160102 | System busy; retry later |
1160103 | Illegal request parameter |
1160104 | RPC chain ID does not match the configured network |
1160201 | Data not found |
1160202 | Duplicate data |
1160301 | Invalid status |
1160401 | Merchant not found; complete B402 onboarding in the same Project that owns the API Key |
1160402 | Merchant account is disabled |
1160403 | Amount exceeds the single-transaction limit |
1160404 | Amount exceeds the merchant daily limit |
1160405 | Amount exceeds the payer daily limit |
1160406 | Payer address is blocked |
1160407 | Address rejected by sanctions controls |
1160408 | B402 merchant rate limit exceeded |
1160409 | Daily gas-sponsored settlement budget reached |
Verify invalidReason
When Verify returns data.isValid: false, invalidReason can include:
insufficient_fundsinvalid_exact_evm_payload_signatureinvalid_exact_evm_payload_authorization_valid_afterinvalid_exact_evm_payload_authorization_valid_beforeinvalid_exact_evm_payload_authorization_value_mismatchinvalid_exact_evm_payload_recipient_mismatchinvalid_networkinvalid_payloadinvalid_payment_requirementsinvalid_schemeunsupported_schemeinvalid_x402_versioninvalid_transaction_stateunexpected_verify_error
invalidMessage is optional diagnostic context for malformed payload or requirements. Do not parse
it for control flow.
Settle errorReason
When Settle returns data.success: false, errorReason uses the same applicable x402 reason values
and may also be unexpected_settle_error. Use the structured reason for program logic and retain
the optional errorMessage only for diagnosis.
Retry Guidance
- Retry HTTP 429,
1160102, and transient 5xx/503 errors with exponential backoff and jitter. - Do not retry signature, payload, permission, merchant-disabled, or limit errors without correcting the cause.
- If Settle returns a non-empty transaction hash, reconcile that transaction before retrying.
- Reusing the same signed authorization is safe because Settle is idempotent; generating a new authorization may create a distinct payment.
Last modified on