状态码

顶层 HTTP 错误

请求在端点成功返回前被拒绝时，使用下面的 Kratos 错误信封。

{
  "code": 503,
  "reason": "PROVIDER_UPSTREAM_UNAVAILABLE",
  "message": "the selected provider is unreachable; retry later",
  "metadata": {}
}

reason 是稳定、机器可读的值。按它写分支。
code 是 HTTP 状态码在 JSON body 中的重复值。
message 是给人阅读的说明，不是稳定分支键。
metadata 只包含该 reason 明确允许的字段，例如批量 maxSize。

对外 reason 表

每个 operation 只列自身请求路径可能产生的 reason。未通过 gateway 对外许可的下游 reason 会折成 GATEWAY_PROVIDER_UNAVAILABLE。

HTTP	`reason`	发生了什么	怎么处理
400	`GATEWAY_MALFORMED_BODY`	请求体不符合本端点 schema。未知字段、拼错的字段名、错误大小写或错误类型都会在筛查前被拒绝。	按端点 schema 修正请求体。不要按 message 文案写分支；它给人阅读，措辞可能变化。
400	`PROVIDER_INVALID_ADDRESS`	地址在请求体指定的链上格式非法。	修正地址或链后重新请求。
400	`PROVIDER_UNSUPPORTED_CHAIN`	所选厂商不为这个能力提供该链。	先按厂商与能力调用“列出能力链”，再从返回链集中选择，或改选另一家已启用厂商。
400	`PROVIDER_UNSUPPORTED_TRANSACTION`	所选厂商拒绝按本次链、方向、output address 或 asset 筛查这笔交易。	修正交易请求；原样重试没有用。
400	`PROVIDER_INVALID_TRANSACTION`	交易哈希在请求指定的链上格式非法。	修正哈希或链后重新请求。
400	`PROVIDER_INVALID_REQUEST`	平台在调用厂商前拒绝了请求：缺少必填字段，或取值非法。	按端点 schema 修正请求；原样重试没有用。
400	`PROVIDER_INVALID_PAGE_TOKEN`	cursor 非法。cursor 不透明，必须来自上一页响应的 nextCursor。	第一页不带 cursor；之后把每页的 nextCursor 原样作为下一次请求的 cursor。
400	`PROVIDER_BATCH_INVALID`	地址批量为空或缺失；proto3 在线缆上无法区分这两种形态。	至少提交一个地址。
400	`BATCH_SIZE_EXCEEDS_PROVIDER_LIMIT`	批量超过所选厂商的单次上限。错误 metadata 会带 provider、requested 与 maxSize。	按不超过 maxSize 拆批后重试。“列出可用厂商”会在提交前返回同一个 batch.maxSize。
400	`PROVIDER_CAPABILITY_UNSUPPORTED`	所选厂商不提供本端点要求的能力。	选择声明该能力的已启用厂商，或省略 provider 使用租户默认厂商。平台返回错误，不用空结果冒充已筛查。
400	`TENANT_VENDOR_NOT_BOUND`	请求指名的厂商未对本租户启用。平台不会静默回落到默认厂商。	使用“列出可用厂商”返回的一家，或省略 provider 使用租户默认厂商。
401	`GATEWAY_CREDENTIAL_INVALID`	请求未通过 API 凭证认证。	检查 Authorization header 与凭证后再试。
404	`PROVIDER_NOT_FOUND`	该厂商 slug 未在平台登记。	使用“列出可用厂商”返回的 slug。
404	`SANDBOX_ADDRESS_NOT_FOUND`	没有录制数据匹配本次厂商、能力、链、主体与请求形状。	改用沙箱清单中的主体，或使用生产凭证。同一沙箱请求原样重试仍会失败。
404	`PROVIDER_TRANSACTION_NOT_FOUND`	哈希格式合法，但请求指定的链上找不到该交易。	交易尚未确认时可重试；否则核对哈希是否属于这条链。
404	`SCREENING_JOB_NOT_FOUND`	批量任务不存在，或不属于本租户；两种状态刻意不区分。	使用提交批量时返回的 jobId，并用创建它的凭证查询。
409	`TENANT_NO_VENDOR_BINDING`	本租户没有启用任何厂商，因此没有发起厂商调用。	联系支持人员为租户启用厂商。
409	`PLATFORM_DEFAULT_VENDOR_MISSING`	租户没有厂商绑定，平台也没有默认厂商可用于创建绑定。	联系支持人员；修改请求无法修复平台配置。
409	`TENANT_VENDOR_BINDING_INVALID`	租户启用的厂商中没有且仅有一家默认厂商，平台拒绝任意选择。	联系支持人员修复租户厂商绑定。
429	`GATEWAY_QUOTA_BALANCE_EXHAUSTED`	你所在组织的累计筛查额度已用尽；所有 API Key 共用这一份。没有任何时钟会把它补回来。	联系客户经理追加额度；在此之前重试无效。
429	`PROVIDER_RATE_LIMITED`	所选厂商对上游调用限流；这与你的筛查额度是两件事。	退避后重试，或改选另一家已启用厂商。
501	`GATEWAY_ENDPOINT_NOT_IMPLEMENTED`	已发布端点当前未由上游服务实现。	不要原样重试；改用其他可用端点或联系支持人员。
502	`GATEWAY_PROVIDER_UNAVAILABLE`	网关没能从 provider 服务取得可安全对外的权威响应。	稍后重试；不要把该响应当成低风险结论。
502	`PROVIDER_MALFORMED_RESPONSE`	所选厂商已响应，但平台无法把响应归一为已发布契约。	重试一次；重复出现时带 trace id 反馈。不要把它理解为未发现风险。
503	`TENANT_VENDOR_UNAVAILABLE`	显式选择的厂商，或省略 provider 时的租户默认厂商，对本次请求不可用：provider 行可能缺失或已停用，也可能没有已登记适配器。	改选另一家已启用厂商；没有可选厂商时，联系支持人员修复 provider 或租户绑定配置。
503	`PROVIDER_UPSTREAM_UNAVAILABLE`	所选厂商不可达或超时，没有返回可用响应。	退避后重试，或选择另一家已启用厂商。当前没有形成筛查结论。
503	`PROVIDER_DISABLED`	所选厂商已停用，或没有可用的集成配置。	选择另一家已启用厂商，或联系支持人员。
503	`GATEWAY_ACCOUNT_UNAVAILABLE`	网关无法通过账户服务验证凭证，因此拒绝请求。	稍后重试；不要仅凭该响应更换凭证。
503	`GATEWAY_QUOTA_UNAVAILABLE`	网关无法确认额度扣减是否成功，因此没有执行筛查。	稍后重试。重试可能成功，且同一次尝试不会被重复扣减。

HTTP 状态码不能代替 reason

多个 reason 可以共用一个 HTTP 状态，但处置动作不同。

503 既可能表示所选厂商暂时不可用，也可能表示租户厂商配置要修；重试前先看 reason。
502 表示 gateway/provider 无法形成可安全对外的归一响应，不是低风险结论。
409 表示租户/厂商配置状态，不是筛查请求体格式错误。
GATEWAY_QUOTA_BALANCE_EXHAUSTED 是你所在组织的累计筛查额度，所有 API Key 共用；PROVIDER_RATE_LIMITED 是所选厂商的上游限流。

先按 reason 分支；metadata 只读取该 reason 文档明确列出的键。

批量受理与单项失败

提交地址批量返回 202 Accepted。受理前判为非法或重复的地址进入 rejected；accepted 地址异步执行。

accepted 单项后续失败时，ScreeningJobResult.error.reason 返回闭集 enum，没有诊断文本字段。progress.total 是受理地址数，done 是成功终态数，failed 是失败终态数；done + failed == total 时任务终止。

批量单项失败 reason

批量受理后，单项失败会在 ScreeningJobResult.error.reason 返回下面的 enum。它们不是顶层 HTTP reason，也不携带诊断文本字段。

单项 reason	发生了什么	怎么处理
`SCREENING_JOB_ITEM_ERROR_REASON_UNSPECIFIED`	protobuf 保留的零值。符合契约的失败单项不会返回它。	把它当作畸形响应并联系支持人员；不要据此推断重试或修改输入是否有用。
`SCREENING_JOB_ITEM_ERROR_REASON_UPSTREAM`	本批次的厂商调用不可达、超时或被限流。	退避后重提批次，或改选另一家提供地址批量能力的已启用厂商。
`SCREENING_JOB_ITEM_ERROR_REASON_SANDBOX_NOT_FOUND`	沙箱没有录制这份完整请求与有序地址组合。	改用完全一致的已录制组合；原样重试不会成功。
`SCREENING_JOB_ITEM_ERROR_REASON_VENDOR_ITEM`	厂商明确把这条已受理地址标为失败。	不能把它当成干净结果。核对地址与所选厂商；原样重试不保证有用。
`SCREENING_JOB_ITEM_ERROR_REASON_VENDOR_NO_ANSWER`	厂商批量响应漏掉了这条已受理地址。	单独重提该地址；若厂商再次漏答，携带 jobId 联系支持人员。
`SCREENING_JOB_ITEM_ERROR_REASON_PLATFORM`	平台无法归一或确认这条地址的厂商结果归属。	重试一次；重复出现时携带 jobId 联系支持人员，不能把它理解为干净结果。
`SCREENING_JOB_ITEM_ERROR_REASON_EXECUTOR`	批量执行器未能执行或完成这条已受理地址；没有形成厂商结论。	稍后重新提交任务；重复出现时携带 jobId 联系支持人员。