| Empty / null response | Request missing PAYMENT-SIGNATURE or X-PAYMENT header | Include PAYMENT-SIGNATURE or X-PAYMENT in the request after signing |
| invalid payment header | PAYMENT-SIGNATURE content is invalid | Check for truncation / character set issues / multiple base64 encodings |
| param_mismatch | Required fields missing, address / nonce format invalid, or other parameter issues | Verify that parameters in the signature match the response |
| toAddr mismatch | Pay-to address does not match the recipient address in the response, or recipient address is the zero address | Recipient address must match exactly and must not be 0x0000… |
| amount mismatch | Signed amount does not match the amount in the response | Align the amount with the response; the value in EIP-3009 must equal the amount in the response |
| unsupported_chain | The chainIndex resolved from network is not supported | Currently only X Layer (eip155:196) is supported |
| payer_blocked | authorization.from has triggered a business risk control rule | Contact OKX business team / submit a risk control appeal |
| risk_address | payer or payTo has triggered a compliance risk control rule (blacklist / sanctioned address) | This address cannot be used for x402; switch to a different address |
| resource mismatch | The interface URL at signing time ≠ the current request URL | Always use the current request URL when signing; do not reuse payloads from other URLs |
| no matching payment option | The payment token does not match the token required by the endpoint | Sign using the token specified in the response |
| invalid_signature | Signature format is invalid (length, r/s range, low s, v value); deferred: Ed25519 verification failed | Use the OKXEvmSigner provided by OKX; do not manually construct EIP-712; tampered value/from cannot be verified |
| not_yet_valid | validAfter > now | Check system clock |
| expired | In exact mode, validBefore <= now (no 60s grace period currently) | Check system clock |
| invalid signature, nonce_used | The EIP-3009 nonce has already been consumed on-chain | Do not replay; generate a fresh 32-byte random nonce and re-sign |
| insufficient_balance | Address balance is insufficient to cover the cost of this call | Top up the balance or reduce concurrent payments |
| onchain_error | On-chain multicall RPC call failed / sub-call returned failure | Usually caused by node instability; retry the request |
| payment processing | Duplicate request with the same signature within the cache window | Do not resubmit the same signature within the cache window |
