错误处理

错误处理先看 HTTP 状态和当前入口语境，再决定是否重试。OpenAI Chat 与 Responses 入口的错误使用 error.message、error.type 和 error.code；Anthropic 入口的错误使用 Anthropic 错误信封， 不要假定其中存在 code 字段。余额不足时，OpenAI 入口返回 HTTP 429 与 error.type=insufficient_quota，并在 error.code 保留具体原因；Anthropic 入口返回 HTTP 402 与 error.type=billing_error。

平台请求编号

响应头 x-request-id 与 request-id 是 Token Factory 独立生成的同一个请求编号；Anthropic 错误体的 request_id 与响应头一致。联系支持时提供该编号、请求时间和 HTTP 状态，无需提供 API Key 或完整请求正文。

请求编号用于排查。Responses 的 response.id 用于资源与上下文续接，两者不可互换。

错误与处理动作

invalid_api_key

• 常见触发：Key 缺失、无效或已停用。
• 建议动作：检查当前环境的鉴权头和 Key 状态。
• 自动重试：否；重复风险：无。

permission_denied

• 常见触发：当前 API Key 无权执行该 OpenAI 协议操作。
• 建议动作：检查 API Key 权限与当前入口的模型可见性。
• 自动重试：否；重复风险：无。

permission_error

• 常见触发：当前 API Key 无权执行该 Anthropic 协议操作。
• 建议动作：检查 API Key 权限与当前入口的模型可见性。
• 自动重试：否；重复风险：无。

model_not_found

• 常见触发：模型不存在、未上架或当前不可用；兼容错误状态可能为 400 或 404。
• 建议动作：核对模型名称与请求地址；持续出现时提供平台请求编号联系支持。
• 自动重试：否；重复风险：无。

MODEL_ROUTING_PROTOCOL_UNSUPPORTED

• 常见触发：当前模型不可用；保留此错误码供既有客户端识别。
• 建议动作：核对模型名称与当前入口的模型列表；持续出现时联系支持。
• 自动重试：否；重复风险：无。

MODEL_ROUTING_NOT_CONFIGURED

• 常见触发：当前模型服务不可用；保留此错误码供既有客户端识别。
• 建议动作：稍后重试；持续出现时提供平台请求编号联系支持。
• 自动重试：视情况；重复风险：无。

MODEL_ROUTING_POLICY_INVALID

• 常见触发：当前模型服务不可用；保留此错误码供既有客户端识别。
• 建议动作：停止连续重试，保留平台请求编号联系支持。
• 自动重试：视情况；重复风险：无。

MODEL_ROUTING_NO_AVAILABLE_ROUTE

• 常见触发：当前模型服务不可用，返回 HTTP 503；保留此错误码供既有客户端识别。
• 建议动作：提供平台请求编号联系支持，确认服务恢复后再发送。
• 自动重试：否；确认服务恢复后再发送。重复风险：无，尚未执行模型调用。

insufficient_balance

• 常见触发：通用余额不足。
• 建议动作：补足余额后由业务明确发起新请求。
• 自动重试：否；重复风险：无。

balance_daily_limit_exceeded

• 常见触发：余额日限额已触发。
• 建议动作：调整限额或等待下个自然日。
• 自动重试：否；重复风险：无。

request_too_large

• 常见触发：请求体超过 Token Factory 当前接收上限；普通 OpenAI 入口返回 413、invalid_request_error 与该错误码，Anthropic 入口返回 413 与 request_too_large 错误类型。
• 建议动作：缩小请求体后再发送。图片编辑按官方逐图、蒙版和最多 16 张图片的限制准备 multipart；平台为该入口提供 805 MiB 总请求体门禁，该总门禁不放宽逐个文件限制。
• 自动重试：否；重复风险：无。

invalid_request_error

• 常见触发：请求结构、必填字段或本地校验不满足。
• 建议动作：修正请求后重新发送。
• 自动重试：否；重复风险：无。

conflict_error

• 常见触发：请求与当前资源状态冲突。
• 建议动作：读取最新状态后修正请求；只有确认冲突是暂态时才稍后重试。
• 自动重试：视情况；重复风险：中到高。

unprocessable_entity

• 常见触发：请求结构正确，但当前请求无法处理。
• 建议动作：按错误信息修正参数或输入内容，不要原样重试。
• 自动重试：否；重复风险：无。

method_not_allowed

• 常见触发：请求方法不是当前公开地址允许的方法。
• 建议动作：改用接口文档列出的 HTTP 方法。
• 自动重试：否；重复风险：无。

unsupported_media_type

• 常见触发：Content-Type 与当前公开地址要求的媒体类型不一致。
• 建议动作：按接口文档发送正确的 Content-Type 和请求体编码。
• 自动重试：否；重复风险：无。

旧版 overloaded_error

• 常见触发：旧版服务返回的过载类型，保留此说明供历史记录排查；当前服务繁忙使用 503，Anthropic 错误类型为 api_error。
• 建议动作：使用指数退避并限制重试次数；流式请求先确认是否已收到输出。
• 自动重试：是，退避后；重复风险：中到高。

service_unavailable

• 常见触发：模型服务暂不可用，返回 HTTP 503；这不表示客户 Key、余额或额度有问题。
• 建议动作：保留平台请求编号，稍后重试或联系支持；先确认业务能否安全重复执行。
• 自动重试：视情况；重复风险：中到高。

service_busy

• 常见触发：模型服务繁忙，返回 HTTP 503；这不表示客户触发了账户限速。
• 建议动作：存在 Retry-After 时参考其中的非负秒数或 HTTP 日期，并限制重试次数；已收到输出时先确认是否允许重新执行。
• 自动重试：视情况；重复风险：中到高。

context_length_exceeded

• 常见触发：输入超过模型上下文限制，返回 HTTP 400；Anthropic 使用 invalid_request_error。
• 建议动作：缩短输入或减少历史上下文后重新发送。
• 自动重试：否，先修改输入；重复风险：无。

missing_required_parameter

• 常见触发：缺少已知公开参数，返回 HTTP 400；Anthropic 使用 invalid_request_error。
• 建议动作：按受控错误提示与接口文档补齐参数；错误不会回显输入值或自定义字段。
• 自动重试：否，先修改请求；重复风险：无。

invalid_parameter

• 常见触发：已知公开参数类型或格式不正确，返回 HTTP 400；Anthropic 使用 invalid_request_error。
• 建议动作：按错误提示与文档修正参数类型或格式；错误不会回显输入值或自定义字段。
• 自动重试：否，先修改请求；重复风险：无。

upstream_usage_missing

• 常见触发：服务响应缺少可验证的用量信息，返回 HTTP 502。
• 建议动作：保留平台请求编号联系支持，确认业务可安全重复后再发送。
• 自动重试：视情况；重复风险：中到高。

流式 upstream_response_invalid

• 常见触发：流式响应未满足接口约定，以对应协议的流式错误结束。
• 建议动作：将本次调用视为失败，保留平台请求编号；不要把已收到部分内容视为正常完成。
• 自动重试：视情况；重复风险：中到高。

upstream_error

• 常见触发：服务响应异常，返回 HTTP 502。
• 建议动作：记录请求意图，按业务幂等性决定有界重试。
• 自动重试：视情况；重复风险：中到高。

upstream_timeout

• 常见触发：请求处理超时，返回 HTTP 504。
• 建议动作：先确认业务是否允许未知结果重放。
• 自动重试：视情况；重复风险：中到高。

internal_error

• 常见触发：平台内部错误。
• 建议动作：保留平台请求编号并稍后重试或联系支持。
• 自动重试：视情况；重复风险：中到高。

旧套餐入口错误

套餐暂未开放。旧配置仍可能返回以下错误码：insufficient_package、package_expired、 model_not_in_package、package_5h_quota_exhausted、package_weekly_quota_exhausted、 package_concurrency_limited、package_input_too_large、package_output_limit_exceeded。 这些错误分别涉及套餐权益、有效期、模型范围、窗口额度、并发或输入输出限制，不属于当前按量接入流程。

先停止自动重试并核对请求路径；旧套餐路径不会自动改扣余额。需要按量接入时，按API 文档 或对应工具教程显式配置余额地址，确认计费方式后再发起新请求。

服务失败与流式错误

Token Factory 对服务失败返回受控错误，不返回内部服务的身份、账户信息、地址或自由错误文本。 客户自身的认证、余额和限速错误仍按上述规则处理。

流式响应开始后，HTTP 状态已经发送；即使是 HTTP 200，仍需检查 SSE 错误事件及协议终态。

重试前的判断

先按本页对应错误修正配置或判断服务状态；部分输出、超时和连接中断的处理，以及各协议的完成判定，统一见流式与重试。