错误码查询

报错时按三层的顺序看：HTTP 状态码 → error_code → 错误文案。文案是给人看的，程序判断只看前两层。

第一层：HTTP 状态码

先看状态码，它决定这个请求到底成没成：

状态码	含义
401	密钥无效
402	余额不足
403	账户没充值被闸门拦（error.code = recharge_required，充一次就放行），或密钥策略是「自定义」而白名单里没这个模型的线路
404	路径不对 —— 四种协议的端点不一样
429	请求过多 —— 退避重试
5xx	服务端错误 —— 重试

非 200 时，响应里的 error 才是 {"message": "...", "type": "..."} 对象。

第二层：error_code

任务级失败会带一个顶层的 error_code，能不能重试看它：

error_code	含义	怎么办
content_policy_violation	内容审核不过	改输入，别重试
invalid_request	参数或素材有问题	改输入，别重试
insufficient_balance	余额不足	去平台充值
quota_exceeded	这把 Key 配额用完	提额或换 Key
key_config_error	这把 Key 没开这个模型，或白名单里排除了它所有线路	去密钥管理补配置
channel_unavailable	这条线路没了	5–30 秒后重试，最多 3 次
upstream_error	上游抽风	5–30 秒后重试，最多 3 次
server_error	服务端错误	5–30 秒后重试，最多 3 次

两条规则：

• 表里没有的值一律按可重试处理。已有的值含义不会变，将来可能加新的
• retryable 是遗留字段，只有 API Key 配额不足那一种情况会带 false；其他情况以 error_code 为准。data.reason_code 存在时跟 error_code 一致

这个字段出现在三个地方：任务失败时（state=failed）、提交任务就失败时（code != 200，没建出任务）、以及 notify_url 回调的 body。

第三层：文案

error 字段和 msg 里的文字只给人看，别拿它做分支判断 —— 同样的失败在不同线路上文案可能不一样。

任务状态的判定

轮询 GET /v1/skills/task-status 时：

• is_final = true 就必须停，别再接着轮询
• 间隔 5 秒一次，别太频繁
• 超过 7200 秒（2 小时）还没完成，当超时处理，停止轮询并告知用户
• state 和 is_final 才是终态依据；status / status_group 是按请求语言翻译的，给人看的
• progress 是数字字符串，没有百分号（"0"、"99"、"100"）
• cost 随阶段变：跑着的时候是提交时预扣的量，成功后是实际结算量，失败退款后是 0（退款额看 refunded_amount）。扣了多少以 is_final = true 之后的值为准
• 老端点 GET /v1/media/status 无错时 error 是空字符串 ""，跟 /v1/skills/task-status 的 null 不一样，别混

同步调用

四个聊天协议（/v1/chat/completions、/v1/responses、/v1/messages、Gemini generateContent）和图片同步生成（/v1/images/generations、/v1/images/edits）的响应体里没有 task id，它在响应头 X-Task-Id 里 —— 拿它调 task-status 就能查这次调用实际花了多少。