核心指南

处理 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 或输入不正确修改请求,不要原样重发
401API 密钥缺失、无效、过期或已撤销更换密钥
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_keyAPI 密钥缺失、无效、已停用或撤销检查 Authorization 请求头和密钥内容
expired_api_keyAPI 密钥已过期创建或选择一枚有效密钥
insufficient_balance余额无法支付这次请求充值、缩小请求或选择价格更低的模型
quota_exceeded这枚 API 密钥达到自身限额提高限额,或使用另一枚有权限的密钥
model_not_allowed这枚密钥不能使用所选模型修改模型范围,或改用已开放模型
user_suspended、account_restrictedHTTP 403。账号当前不能使用 API带上请求 ID 联系支持
invalid_delivery_policyHTTP 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_typeHTTP 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_urlTokenLab 无法使用图片 URL:它不是有效的 HTTP(S) URL 或图片 data URI,或者图片地址没有返回图片;param 指明字段名发送公开的 HTTPS 图片 URL 或支持的 data URI
content_policy_violationHTTP 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_unavailableHTTP 503。请求本身有效,但在这次请求可用的路由上,TokenLab 暂时无法为该模型和操作的组合计价。这次请求不扣费,retryable 为 false不要原样重发;换用其他模型或操作,或带上请求 ID 联系支持
idempotency_conflictHTTP 409。这个 Idempotency-Key 已属于另一个请求,TokenLab 没有执行本次请求新请求换用新的键
idempotency_replay_unavailableHTTP 409。这个 Idempotency-Key 已经用过,TokenLab 没有可以返回的结果,也没有再次执行请求如果第一次请求可能还在执行,稍后用同一个键重试;否则换用新的键。见用幂等键安全重试
idempotent_response_not_replayableHTTP 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 或完整的私密提示词。

从请求详情到调查和人工支持

本页内容