| Empty / null response | Request did not include 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 / encoding issues / multiple base64 nesting |
| param_mismatch | Missing required fields or invalid parameters (address / nonce format) | Verify that parameters in the signature match the expected values |
| toAddr mismatch | PayTo address does not match or is zero address | Ensure the address matches exactly and is not 0x0000… |
| amount mismatch | Signed amount does not match returned amount | Ensure value in EIP-3009 signature equals the returned amount |
| unsupported_chain | Parsed chainIndex from network is not supported | Currently only X Layer (eip155:196) is supported |
| payer_blocked | authorization.from triggered risk control rules | Contact OKX support / risk team |
| risk_address | payer or payTo is flagged (blacklist / sanctioned address) | Use a different address |
| resource mismatch | Signed URL does not match request URL | Use the exact request URL when signing; do not reuse payload |
| no matching payment option | Payment token does not match required token | Sign using the token specified in the response |
| invalid_signature | Invalid signature format (length, r/s range, v value, etc.) | Use OKXEvmSigner; avoid manual EIP-712 construction |
| not_yet_valid | validAfter > now | Check system time |
| expired | validBefore <= now | Check system time |
| invalid signature, nonce_used | Nonce already used on-chain | Generate a new 32-byte nonce and sign again |
| insufficient_balance | Insufficient balance | Fund the account or reduce concurrent payments |
| onchain_error | On-chain RPC / multicall failure | Retry the request |
| payment processing | Duplicate request within cache window | Avoid reusing the same signature within cache period |
