核心指南
处理 API 错误
根据错误码判断问题，只在有用时重试，并保留请求 ID
程序应根据 HTTP 状态和 code 处理错误。message 是写给人看的，文案可能调整，不适合用来做程序判断。
Chat Completions 和 Responses 使用 OpenAI 风格的 error 对象。Anthropic Messages 与 Gemini 保留各自的错误格式，不能用同一个解析器处理所有 TokenLab API。
{
"error": {
"message": "Human-readable description",
"type": "error_type",
"code": "error_code",
"param": "parameter_name",
"retryable": true,
"retry_after": 30
}
}TokenLab 返回的 OpenAI 兼容错误一定包含 message 和 type，其他字段只在有对应信息时出现。
HTTP 状态
| 状态 | 含义 | 通常怎么处理 |
|---|---|---|
400 | 字段、模型 ID 或输入不正确 | 修改请求，不要原样重发 |
401 | API 密钥缺失、无效、过期或已撤销 | 更换密钥 |
402 | 余额不足，或 API 密钥已达到限额 | 充值、提高限额或缩小请求 |
403 | 当前密钥不能使用这个资源或模型 | 修改密钥权限或更换模型 |
404 | 资源不存在或已经失效 | 检查 ID，以及创建资源时使用的 API 密钥 |
413 | 请求或上传文件过大 | 缩小到模型或 API 文档注明的限制内 |
429 | 已达到请求限额 | 按 Retry-After 等待 |
500–504 | 服务不可用或网络故障 | 仅在 retryable 为 true 时重试，并遵守 retry_after 和次数限制 |
常见错误码
| 错误码 | 含义 | 需要修改什么 |
|---|---|---|
invalid_api_key | API 密钥缺失、无效、已停用或撤销 | 检查 Authorization 请求头和密钥内容 |
expired_api_key | API 密钥已过期 | 创建或选择一枚有效密钥 |
insufficient_balance | 余额无法支付这次请求 | 充值、缩小请求或选择价格更低的模型 |
quota_exceeded | 这枚 API 密钥达到自身限额 | 提高限额，或使用另一枚有权限的密钥 |
model_not_allowed | 这枚密钥不能使用所选模型 | 修改模型范围，或改用已开放模型 |
model_not_found | 模型 ID 不存在或当前不可用 | 从 /v1/models 选择当前模型 ID |
context_length_exceeded | 输入超过模型上下文长度 | 删除无关历史，或更换上下文更长的模型 |
rate_limit_exceeded | 当前时间窗口内请求过多 | 按 Retry-After 等待 |
payload_too_large | 请求体或文件超过 API 限制 | 缩小或压缩输入 |
all_channels_failed | 所选模型无法处理这次请求 | 仅在 retryable 为 true 时重试，并遵守 retry_after 和次数限制 |
timeout_error | 请求未在规定时间内完成 | 只在操作可以安全重复时重试 |
503 all_channels_failed 或 503 delivery_tier_unavailable 不一定是临时故障。如果所选 Delivery 档位没有支持当前操作的供应，retryable 为 false，且不返回 retry_after，不要原样重试。更换模型前，通过 GET /v1/models 检查对应操作和 Delivery 的可用性。名称相近不代表可用；未经验证的替代模型不会列出。
部分 OpenAI 兼容错误还会带有 did_you_mean、suggestions、alternatives、hint、retryable 或 retry_after。具体用法见让 Agent 读懂 API 错误。
如果请求走的是 Official 线路，且上游服务拒绝了请求本身（例如不接受的输入或内容政策判定），错误里还会带 upstream：其中 message 是上游给出的原文，已知时还有 code 和 source（上游服务名称）。Anthropic Messages 和 Gemini 的错误会在各自的 error 对象里带同样的字段。请继续按 code 和 type 分支处理；upstream.code 由上游服务定义，可能变化。
什么时候可以重试
| 错误 | 能否原样重发 |
|---|---|
400、401、402、403、404、413 | 不能。需要修改请求、凭据、余额、权限或输入。 |
429 | 可以，但必须等待服务端给出的时间。 |
500–504 | 仅在 retryable 为 true 时重试，并遵守 retry_after 和次数限制 |
| 收到任何响应前连接中断 | 视情况。创建类请求要确认是否已经产生任务或其他结果。 |
| 流式输出已经开始后中断 | 不能把残缺内容标成完成；重发可能得到不同结果或产生第二次费用。 |
创建图片、视频、音乐、3D 或 Worlds 任务时，收到任务 ID 就立即保存。创建请求超时后，请确认没有任务记录再重新提交。
保存请求 ID
响应头会提供请求 ID，用于查询这次请求。请同时记录 API 地址、模型、时间，以及你自己的用户或任务 ID。异步任务还应保存 task_id 和返回时的 billing_transaction_id。
联系支持时请附上这些 ID 和脱敏示例。不要发送 API 密钥、管理令牌、私密媒体、签名 URL 或完整的私密提示词。