状态与支持
先自己排查，再升级问题
Section titled “先自己排查，再升级问题”几乎所有被报上来的故障都落在五种情况里，而且各有可区分的特征：
| 现象 | 可能原因 | 看哪一页 |
|---|---|---|
昨天还正常的调用返回 401 unauthorized | key 被轮换、被停用，或某条代码路径漏了请求头 | 认证 |
402 insufficient_balance | 余额不足以覆盖本次提交的预占 | 账户与余额 |
请求返回 200，但什么都没扣费 | 整个组合全部失败；HTTP 状态不等于结果 | 计费与退款 |
| 同一个请求时而成功时而失败 | 限流，或同一个 Idempotency-Key 被不同请求体复用 | 限流规则、幂等与重试 |
批量任务停在 processing，last_progress_at 不再前进 | 任务确实卡住了，而不是慢 | 任务状态 |
最后一条值得说清楚：故障信号是时间戳停住，不是耗时变长。 一个 50 万行的任务跑很久是正常的；last_progress_at 不动的任务才是要升级的问题。
联系支持时请带上
Section titled “联系支持时请带上”下面每个字段都是接口自己返回的，所以带着它们不增加你的成本，却能省掉一个来回：
| 带上 | 从哪里来 |
|---|---|
request_id | 每个实时响应，包括带响应体的失败 |
task_id | 每次批量提交，以及每个任务状态响应 |
api_key_id | GET /v1/api-key —— 在不暴露 key 的前提下指明是哪一个 |
| 确切的 HTTP 状态与响应体 | 你自己的日志；尤其是其中的 code 字段 |
| 到秒的 UTC 时间戳 | 你自己的日志 |
| 你发出的请求（key 打码） | 你自己的代码 |
绝不要在支持请求里粘贴 API key。api_key_id 已经能指明是哪个 key，而 key 本身能直接动你的余额。
账户级通告 —— 计划维护、容量降级 —— 会出现在控制台，余额与记录也在那里。同样的情况会以错误码而非散文的形式直接暴露给你的集成：
| 错误码 | 对运行中的集成意味着什么 |
|---|---|
detection_capacity_unavailable | 当前没有检测容量。退避重试；未产生扣费。 |
realtime_route_unavailable | 没有可用的实时路由。退避重试。 |
realtime_rate_limiter_unavailable | 限流器本身不可用，无法做出准入判断。稍后重试。 |
realtime_fact_cache_unavailable | 某个实时依赖不可用。稍后重试。 |
这些都是 503，且都属于”等待后重试”组 —— 完整分组（包括哪些失败可以用同一个 Idempotency-Key 安全重试）见错误码。
平台当前的情况
Section titled “平台当前的情况”有两个运维事实可以从外部验证，在提交故障前值得知道：
- 接口部署在 Cloudflare 之后，所以网络路径与 TLS 终结由 Cloudflare 承担，而不是单台源站。
- 每个响应都带
X-RateLimit-Remaining，所以会记录响应头的客户端可以自行区分「被自己的限额限住了」和「服务挂了」，不必问任何人。通用组与检测组的每个响应还带X-RateLimit-Limit；实时检测不带，因为它消耗的是令牌桶，而不是固定的每分钟上限。