核心指南
处理 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 密钥 |
409 | 这个 Idempotency-Key 已经用过:请求体不同(idempotency_conflict),或者 TokenLab 无法返回那次请求的结果(idempotency_replay_unavailable、idempotent_response_not_replayable)。TokenLab 没有再次执行请求 | 新请求换用新的键。是否用同一个键重试,见用幂等键安全重试 |
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 | 这枚密钥不能使用所选模型 | 修改模型范围,或改用已开放模型 |
user_suspended、account_restricted | HTTP 403。账号当前不能使用 API | 带上请求 ID 联系支持 |
invalid_delivery_policy | HTTP 400。X-TokenLab-Delivery-Policy 请求头不是 auto、verified 或 official | 改用这三个值之一,或去掉该请求头 |
model_not_found | 模型 ID 不存在或当前不可用 | 从 /v1/models 选择当前模型 ID |
context_length_exceeded | 输入超过模型上下文长度 | 删除无关历史,或更换上下文更长的模型 |
missing_required_parameter | 缺少必填字段,param 指明字段名,例如音频和图片请求的 model(这些接口没有默认模型) | 补上 param 指明的字段 |
invalid_value | 字段的值不被该模型接受,例如 reasoning_effort 的值;错误信息会列出可用的值 | 改用列出的值之一 |
invalid_response_format_type | HTTP 400。response_format 是对象但没有可用的 type,或 type 取值不被该接口接受;param 为 response_format | 将 response_format.type 设为 text、json_object 或 json_schema;使用 json_schema 时还要发送 json_schema.name 与 json_schema.schema |
invalid_image_url | TokenLab 无法使用图片 URL:它不是有效的 HTTP(S) URL 或图片 data URI,或者图片地址没有返回图片;param 指明字段名 | 发送公开的 HTTPS 图片 URL 或支持的 data URI |
content_policy_violation | HTTP 400。模型供应方的安全检查拒绝了提示词或输入媒体。这次请求不扣费,retryable 为 false。走 Official 线路时,upstream.code 是供应方自己的错误码,例如 moderation_blocked、data_inspection_failed | 检查提示词和媒体,改写后重新提交。见内容安全拦截 |
unsupported_model_capability | 所选 Delivery 档位没有路由支持某个请求参数,例如 operation、resolution、aspect_ratio、duration、输入媒体字段、web_search_options 或 max_tokens。message 会列出不匹配的参数,模型公布了可选值时也会列出这些值 | 删除或修改该参数,或换用其他 Delivery 档位或模型;不要原样重发 |
unpriceable_selection | 视频请求缺少决定价格的选项,TokenLab 无法为它定价;param 指明该选项 | 显式设置 param 指明的字段 |
model_pricing_unavailable | HTTP 503。请求本身有效,但在这次请求可用的路由上,TokenLab 暂时无法为该模型和操作的组合计价。这次请求不扣费,retryable 为 false | 不要原样重发;换用其他模型或操作,或带上请求 ID 联系支持 |
idempotency_conflict | HTTP 409。这个 Idempotency-Key 已属于另一个请求,TokenLab 没有执行本次请求 | 新请求换用新的键 |
idempotency_replay_unavailable | HTTP 409。这个 Idempotency-Key 已经用过,TokenLab 没有可以返回的结果,也没有再次执行请求 | 如果第一次请求可能还在执行,稍后用同一个键重试;否则换用新的键。见用幂等键安全重试 |
idempotent_response_not_replayable | HTTP 409。这个 Idempotency-Key 对应的创建请求,其任务已经结束,TokenLab 无法返回原来的创建响应。响应体顶层带有 task_id,与 error 并列。TokenLab 没有再次执行请求 | 不要用这个键重发。只有需要新任务时才换用新的键 |
rate_limit_exceeded | 当前时间窗口内请求过多 | 按 Retry-After 等待 |
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 由上游服务定义,可能变化。
内容安全拦截
安全检查在模型供应方那里跑,不在 TokenLab。被拦下的请求返回 400,code 为 content_policy_violation,retryable 为 false。响应里的 type 是 invalid_request_error,code 是 content_policy_violation,retryable 为 false,并带一条 hint;走 Official 线路时还带 upstream,其中 source、code、message 是供应方给出的。
TokenLab 归到这个错误下的供应方错误码包括 moderation_blocked、content_moderated、data_inspection_failed、failedoperation.moderationfailed、prompt_blocked、sensitive_content_detected、sensitive_words_detected 和 prohibited_content。供应方用一句话描述同一个判定,例如「request blocked by moderation policy」「this request did not pass the content safety check」,也归为这个码。
因为判定是供应方做的,有三件事随之而定:
- 这次请求不扣费。 拦截发生在计费之前。
- 原样重发还是同一个结果。 不要把这类请求放进重试循环,也不要把
upstream.message当成临时故障。 - TokenLab 不会把同一个请求换一条路由再发一次来绕开判定。 判定针对的是请求本身,不是它当时走的那条线路。
要让请求通过,改请求:改写提示词,或去掉媒体里被拦下的部分。带媒体的请求会同时检查提示词和媒体,两样都要看。每家供应方有自己的政策、只管自己的模型,所以同一段提示词在一个模型上能过、在另一个模型上被拒;upstream.source 写明是哪家拒的。换模型之前先读那家的政策:换供应方是找一个接受你这用途的政策,不是绕开政策。
如果你认为判定有误,带请求 ID、模型 ID 和 upstream.code 联系支持。不要把私有媒体和完整提示词发过来。
什么时候可以重试
| 错误 | 能否原样重发 |
|---|---|
400、401、402、403、404、413 | 不能。需要修改请求、凭据、余额、权限或输入。 |
429 | 可以,但必须等待服务端给出的时间。 |
500–504 | 仅在 retryable 为 true 时重试,并遵守 retry_after 和次数限制 |
| 收到任何响应前连接中断 | 请求属于用幂等键安全重试中列出的请求并带了 Idempotency-Key 时可以:用同一个键和同样的请求体重发。其他情况先确认是否已经产生任务或其他结果。 |
| 流式输出已经开始后中断 | 不能把残缺内容标成完成;重发可能得到不同结果或产生第二次费用。 |
创建图片、视频、音乐、3D 或 Worlds 任务时,收到任务 ID 就立即保存。创建请求超时后,用同一个 Idempotency-Key 和同样的请求体重发,即可拿到原来的任务。没有带键时,先确认没有任务记录再重新提交。
用幂等键安全重试
超时或连接中断时,你无法判断 TokenLab 是否已经执行了请求。给下面列出的请求加上 Idempotency-Key 请求头,同一请求的重试就不会被执行或扣费两次。
- 每次操作使用一个新的唯一值,例如 UUID。键最长 255 个字符。TokenLab 会忽略更长的键,这时请求没有幂等保护:重试会再次执行并再次扣费。
POST /v1/messages/batches例外:键超过 256 个字符时返回400。 - 发送请求前,先把键和你自己的任务记录一起保存。
- 重试时使用同一个 API 密钥、同一个
Idempotency-Key和同样的请求体。 - 除了
409且错误码为idempotency_replay_unavailable的响应,收到其他任何响应后都不要再使用这个键。之后的新尝试换用新的键。 - 关闭 SDK 自动重试(
max_retries=0),由你的代码决定何时复用键。
不带这个请求头时,每次重试都是一个新请求。
创建任务的请求
以下创建请求支持 Idempotency-Key:
POST /v1/videos/generations、POST /v1/music/generations、POST /v1/3d/generations和POST /v1/worlds/generations- 返回任务时的
POST /v1/images/generations和POST /v1/images/edits - 带
"background": true的POST /v1/responses POST /v1/messages/batches
创建请求超时后,原样重发即可。TokenLab 返回原创建请求的结果,不会创建、派发第二个任务,也不会再次扣费。结果通常是原来的任务,id 不变(Responses 返回原来的 response 对象),你继续轮询它即可。对视频、音乐、3D、Worlds 和图片任务,如果第一次创建请求失败,结果也可能是原来的错误。如果这类任务已经结束且 TokenLab 没有保存创建响应,重试会返回 409,错误码 idempotent_response_not_replayable,响应体顶层带有 task_id。
用一个已被接受的键发送不同的请求体,TokenLab 会拒绝请求,也不会创建任务。视频、音乐、3D 和 Worlds 创建请求返回 409,错误码 idempotency_conflict。Message Batches 返回 409,错误类型 conflict_error。图片任务和带 background: true 的 Responses 请求在这种情况下的状态码和错误码不作保证。不要用同一个键重试。
Chat Completions、Responses 和 Messages
POST /v1/chat/completions、不带 background 的 POST /v1/responses 和 POST /v1/messages 对同一个键只执行一次。用同一个键重试时,会得到以下结果之一:
| 情况 | 结果 |
|---|---|
| 第一次请求还在执行 | 409,错误码 idempotency_replay_unavailable |
| 第一次请求在你的客户端断开后才完成;请求不是流式,结果不超过 1 MB,并且你在 24 小时内用同样的请求体重试 | 200,返回原来的响应体,并带 Idempotent-Replayed: true 响应头。TokenLab 不会再次执行或扣费 |
| 这个键已经以其他方式用过,例如:你已收到结果、请求是流式的、结果超过 1 MB,或已超过 24 小时 | 409,错误码 idempotency_replay_unavailable |
| 请求体与第一次不同 | 409,通常是错误码 idempotency_conflict,部分请求返回 idempotency_replay_unavailable |
无论是哪个错误码,409 都表示 TokenLab 没有再次执行请求。带键的流式请求不会被执行两次,但 TokenLab 无法再次发送它的输出。
下面的示例在 Chat Completions 请求超时后用同一个键重试,直到拿到结果:
import os
import time
import uuid
import openai
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=120.0,
max_retries=0,
)
def create_once(messages, model="gpt-5.6-terra", waits=(0, 5, 15, 45)):
key = str(uuid.uuid4()) # Save this key with your job record.
for wait in waits:
time.sleep(wait)
try:
return client.chat.completions.create(
model=model,
messages=messages,
extra_headers={"Idempotency-Key": key},
)
except (openai.APITimeoutError, openai.APIConnectionError):
continue # No response: retry with the same key and body.
except openai.ConflictError as exc:
if exc.code != "idempotency_replay_unavailable":
raise
# The first attempt can still be running. A later retry returns its result.
raise RuntimeError(f"No result for Idempotency-Key {key}")如果最后一次尝试仍然返回 idempotency_replay_unavailable,说明 TokenLab 无法返回那次结果。只有在可以接受再次执行和再次扣费时,才换用新的键重新发送。
保存请求 ID
响应头会提供请求 ID,用于查询这次请求。请同时记录 API 地址、模型、时间,以及你自己的用户或任务 ID。异步任务还应保存 task_id 和返回时的 billing_transaction_id。
联系支持时请附上这些 ID 和脱敏示例。不要发送 API 密钥、管理令牌、私密媒体、签名 URL 或完整的私密提示词。