状态码

在 ChatGPT 中打开

所有错误长得都一样

无论出了什么问题,响应 body 都是同样这四个字段:

{
  "code": 503,
  "reason": "RISK_SCORE_NOT_READY",
  "message": "risk score is still being computed",
  "metadata": { "retry_after": "2" }
}
  • reason —— 按这一个来分支处理。它是「发生了什么」的稳定、机器可读的标识。
  • code —— HTTP 状态,在 body 里重复一遍。
  • message —— 给人读的说明文字。它可能不加通知就改动;不要拿它做匹配。
  • metadata —— 有额外上下文时的键值对。上面的示例带的是 retry_after,单位为秒。

你会收到什么

以下是本站发布的端点会返回的每一个状态与 reason。没有 GATEWAY_ 前缀的取值,稳定程度与带前缀的完全一样 —— 前缀说的是这个结果在哪里被判定的,不是它有多可靠。

HTTPreason发生了什么该怎么处理
400PROVIDER_INVALID_ADDRESS该地址在路径里的那条链上被拒绝 —— 要么它不是那条链上的合法地址,要么情报源拒绝了它。不可重试。改正地址后重新发送。
400PROVIDER_UNSUPPORTED_CHAIN这个端点不覆盖那条链。覆盖范围由每个端点各自决定,所以一个端点接受的链,另一个端点仍可能拒绝。不可重试。改用本端点支持的链。
400PROVIDER_UNSUPPORTED_TRANSACTION仅交易类端点:该交易或它的某个筛查输入被拒绝。在交易 custom-score 端点上,这个结果可能在轮询期间才出现。不可重试。改正请求后重新发送。
401GATEWAY_CREDENTIAL_INVALID该请求没有通过凭证认证。重新发送请求前,检查 Authorization header 与凭证。
429GATEWAY_QUOTA_EXCEEDED该凭证在当前窗口内的请求配额已用完。等限流窗口过去后重试。
502GATEWAY_PROVIDER_UNAVAILABLE我们没能从这个端点背后的情报源拿到权威答案 —— 它不可达、超时、返回了我们无法使用的内容,或者当前不在服务中。不要立即重试。等该情报源恢复服务后再重试。
502RISK_SCORE_TASK_FAILED这次请求背后的异步打分任务进入了终态的、非暂时性的失败。不要继续轮询,也不要复用那个任务。重新发送请求以开启一个新任务。
503RISK_SCORE_NOT_READY异步打分任务没有在响应窗口(几秒)内完成。这是正常的处理中结果,不是失败 —— 深度交易筛查会常态化返回它。可重试。等待 metadata.retry_after 秒后重新发送同一个请求。它通常会接上已经在跑的那个任务、而不是新开一个,但这种复用是常见情况,不是保证。
503GATEWAY_ACCOUNT_UNAVAILABLE网关没能判定该凭证是否有效,因此拒绝了这个请求。重试。不要仅凭这个响应就更换凭证。

为什么只看状态码不够

这些状态里有两个各自承载两种不同的结果,而每种结果需要各自的处理方式:

  • 503 RISK_SCORE_NOT_READY 是分数仍在计算中 —— 等待后重新发送,正在跑的那次通常会继续。503 GATEWAY_ACCOUNT_UNAVAILABLE 是我们压根没能对这个请求作出判定。
  • 502 RISK_SCORE_TASK_FAILED 对那个任务而言是终态 —— 重试需要一个新任务。502 GATEWAY_PROVIDER_UNAVAILABLE 则需要等到情报源恢复服务后再重试。

按 reason 分支,才能把常态的处理中任务与网关判定失败区分开,把终态的任务失败与情报源不可用区分开。

异步风险分

风险打分在上游以任务的形式运行。我们会轮询它几秒,分数落在这个窗口内就把它返回。落不进去的话,你会拿到 503 RISK_SCORE_NOT_READY,并带一个 retry_after 提示。重新发送同一个请求通常会接上已经在跑的那个任务、而不是另开一个 —— 这是常见情况,不是保证。深度交易筛查会常态化进入这个状态;把它当成正常的一步,而不是需要告警的错误。

终态结果包括分数本身、502 RISK_SCORE_TASK_FAILED,以及 —— 在交易 custom-score 端点上 —— 400 PROVIDER_UNSUPPORTED_TRANSACTION,后者只可能在轮询开始之后才出现。出现 RISK_SCORE_TASK_FAILED 意味着那个任务已经没了:重新发送请求以开启一个新的,并停止轮询旧的那个。