错误

一种统一结构、七种类型，以及可以据此分支处理的错误码。

/v1 上所有非 2xx 的响应都具有相同的结构：

{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_too_small",
    "message": "amount must be at least 1.000000 USDT",
    "param": "amount_decimal"
  },
  "request_id": "req_8f2c…"
}

按 type 分支处理，按 code 确定提示信息

type 按你应该如何应对对失败进行分组——这是唯一值得放进响应中的分组方式。

| 类型 | HTTP | 处理方式 | | --- | --- | --- | | invalid_request_error | 400, 404, 409 | 修正请求。原样重试仍会失败。 | | authentication_error | 401 | 修正凭证。 | | permission_error | 403 | 凭证有效，但缺少所需的权限范围。 | | idempotency_error | 409 | 同一个键、不同的请求体。参见幂等性。 | | rate_limit_error | 429 | 逐步拉长间隔后重试。 | | chain_error | 502, 503 | 是链或其 RPC 出了故障，问题不在你。通常是暂时性的。 | | api_error | 500 | 我们的问题。可以重试，并且会通知值班人员。 |

chain_error 之所以与 api_error 分开，是因为补救方式不同：涉及这类错误的付款只是*停滞*了，并没有丢失。

值得处理的错误码

| 错误码 | 含义 | | --- | --- | | missing_api_key / invalid_api_key | 没有可用的凭证。 | | api_key_revoked | 有人刻意吊销了它。 | | live_mode_disabled | 在没有正式模式的部署上使用了正式密钥。 | | kyc_required | 该账户尚未完成身份验证，因此不能使用正式模式。这不是你能在代码中修复的问题——需要由账户所有者在控制台的“设置”中完成。如果想知道何时通过，请订阅 kyc.approved。 | | two_factor_required | 该账户尚未启用双重验证。它与 kyc_required 并列、单独成为一个错误码，因为两者的补救方式毫无共同之处：一个是填写表单并等待他人决定，另一个只需拿起手机花三十秒。 | | terms_acceptance_required | 该账户从未接受过服务条款，因此不能做任何更改。只有写操作返回 403——读操作照常可用，因此在此事未解决期间，控制台依然可以加载，监控程序也能继续读取数据。你发送任何请求都无法解决它：需要账户所有者登录控制台并接受一次，之后他们已持有的所有凭证都会立即恢复可用。已接受过旧版本条款的账户不受此影响；这类账户会在控制台中收到询问。 | | insufficient_scope | 密钥有效，但权限范围不对——或者在需要私密密钥的接口上使用了 pk_ 密钥。 | | missing_idempotency_key | 会修改数据的调用没有携带该请求头。 | | idempotency_key_reused | 同一个键、不同的请求体。 | | idempotency_request_in_flight | 第一次尝试仍在执行中。 | | resource_missing | 没有这个对象，或者它不属于你。 | | amount_too_small / amount_too_large | 超出配置的范围。 | | chain_not_enabled | 你尚未启用该链。 | | no_amount_available | 该地址上所有可用于区分付款的金额都已被占用。请重试。 | | invalid_state_transition | 例如取消一笔已经是 paid 的付款。 | | duplicate_reference | 你的 reference 在此账户中已被使用。 | | mandate_cap_exceeded | 扣款金额超过了客户授权的额度。 | | unknown_api_version | 当前构建不支持的 Paygate-Version。 | | malformed_request_body | 请求体无法解码；没有任何处理程序被执行。 |

这份列表并不详尽，也无意做到详尽。只有当集成必须根据原因进行分支处理时，才值得设立一个错误码；为每条消息都发明一个错误码，只会产生一套没人维护的词汇表。

param

在校验失败时出现，指明出错的字段——这样你就可以把错误消息显示在导致错误的输入项旁边，而不是表单顶部。

request_id

每个错误都会带有它。联系技术支持时请附上它；有了它，日志才能被检索。

安全重试

对 429、chain_error 和 api_error 进行重试。不要重试 400——重试结果不会有任何不同。

对会修改数据的调用，每次重试都必须复用原来的 Idempotency-Key。正是这一点让重试变得安全，而不会变成创建两笔付款的途径。