B402 有两层错误：
- HTTP/Gateway 或 B402 Envelope 错误：鉴权、请求格式、商户状态、限流或基础设施故障。
- x402 业务结果：Verify 和 Settle 返回 HTTP 200，结果位于
data。
Web3 Gateway 错误
| HTTP | Code | 含义 |
|---|---|---|
| 400 | 40001 | 请求参数错误 |
| 401 | 40101 | API Key 缺失、无效、已删除或已禁用 |
| 401 | 40102 | 请求签名缺失或无效 |
| 401 | 40103 | Timestamp 过期或请求重放 |
| 403 | 40104 | API Key 访问策略拒绝请求：检查 B402 Payments 权限、IP 白名单和 Endpoint Allowlist |
| 429 | 42900 | Gateway 限流 |
| 500 | 50000 | Gateway 内部错误 |
| 503 | 50001 | 服务暂时不可用 |
B402 Envelope 错误
| Code | 含义 |
|---|---|
1160101 | 系统错误 |
1160102 | 系统繁忙，请稍后重试 |
1160103 | 请求参数非法 |
1160104 | RPC Chain ID 与配置网络不一致 |
1160201 | 数据不存在 |
1160202 | 重复数据 |
1160301 | 状态无效 |
1160401 | 商户不存在；请在该 API Key 所属的同一个 Project 下完成 B402 开通 |
1160402 | 商户已禁用 |
1160403 | 超过单笔金额上限 |
1160404 | 超过商户日限额 |
1160405 | 超过付款人日限额 |
1160406 | 付款人地址被拦截 |
1160407 | 地址被制裁风控拒绝 |
1160408 | 超过 B402 商户接口限流 |
1160409 | 已达到每日 Gas 代付结算预算 |
Verify invalidReason
Verify 返回 data.isValid: false 时，invalidReason 可能包括：
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
仅提供 Payload 或 Requirements 格式错误的可选诊断信息，不要依赖其文本进行程序分支处理。
Settle errorReason
Settle 返回 data.success: false 时，errorReason 使用适用的相同 x402 Reason，也可能是
unexpected_settle_error。程序逻辑应使用结构化 Reason，errorMessage 仅用于诊断。
重试建议
- HTTP 429、
1160102、临时 5xx/503 错误使用指数退避和 Jitter 重试。 - 签名、Payload、权限、商户禁用或额度错误必须先修正原因，不要直接重试。
- Settle 返回非空 Transaction Hash 时，重试前必须先查询或对账该交易。
- 使用同一个签名授权重试是幂等的；创建新授权可能形成另一笔支付。
Last modified on