错误

Tokener.ai 模型 API 的错误响应格式与错误码。

更新于 2026-10-27
在 GitHub 编辑

模型 API 的每个响应——无论成功或出错——都带有 x-request-id 与 request-id 响应头（req_<32 位十六进制字符>）。联系支持时请附上该值。

非流式错误

出错时返回非 2xx 的 HTTP 状态码与 JSON 响应体，格式与请求所用协议一致。

OpenAI 形态的路径（/models、/models/user、/chat/completions、 /embeddings、/responses）：

JSON
{
  "error": {
    "message": "Invalid API key.",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Anthropic 形态的路径（/messages）：

JSON
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key."
  },
  "request_id": "req_1f2e3d4c5b6a7988a1b2c3d4e5f60718"
}

模型拒绝可识别的参数时，HTTP 400 保留 invalid_request，并在 error.param 中标明参数。例如：

JSON
{
  "error": {
    "message": "Invalid value for parameter 'temperature'.",
    "type": "invalid_request_error",
    "param": "temperature",
    "code": "invalid_request"
  }
}

不支持的字段使用 This model does not support parameter 'store'.。 不兼容的组合使用 Parameters 'tools' and 'reasoning_effort' cannot be used together with this model.。 对于可识别的采样限制，消息说明接受条件： Parameter 'temperature' must be 1 unless 'reasoning_effort' is 'none' with this model.。 单个采样参数受限时，error.param 保留该参数名。Chat 限制同时列出 logprobs、top_p 和 top_logprobs 时，error.param 指向推理强度字段，消息列出这三个参数。 可识别的错误可以列出支持的值或改正方法，例如 This model does not support forced 'tool_choice'. Use 'auto'.。 模型选择错误标明 model；工具历史错误在 Chat/Messages 中标明 messages， 在 Responses 中标明 input。格式类型被拒时，Chat 标明 response_format， Responses 标明 text.format。这些提示说明拒绝原因，不会修改请求参数。 Responses 错误使用 reasoning.effort、text.format 等公开字段路径。 Anthropic 错误在 error.message 中标明参数，不增加 param 字段。 Messages 错误点名可识别的原生字段（如 output_config.effort），并将 stop 映射为 stop_sequences。 被拒的组合涉及来源不明的 effort 字段时，保留组合冲突含义并点名可识别的原生控制参数，不猜测 effort 字段。 后端能确定原生推理字段时，组合错误会点名两个原生字段。 错误仅指向有歧义或 OpenAI 专用字段时，保留 Invalid request.。 无法安全识别参数时，param 保持 null，消息保持 Invalid request.。消息不会包含后端细节。 即使设置 stream:true，流开始前的拒绝也使用此 HTTP 合同；流开始后的错误仍使用下方通用 SSE 合同。

模型不支持存储、缓存管理或安全归因时，可以忽略这些字段：store、prompt_cache_key、 prompt_cache_retention 和 safety_identifier。不提供响应存储的模型会同时忽略 store:true 和 store:false。这类字段不改变输出内容、格式或工具行为。其他不支持的生成控制、非法值或 非法组合仍会失败。未来新增的未知字段仍可能返回 HTTP 400。

流式错误

当 stream: true 且错误发生在流已经开始之后，错误会以一个 SSE 帧的形式出现， 而不是 HTTP 错误状态码。根据路径不同，共有三种形态：

/chat/completions（OpenAI Chat Completions）：

Text
data: {"error":{"message":"Upstream request failed.","type":"upstream_error","param":null,"code":"provider_error"}}

/messages（Anthropic Messages）：

Text
event: error
data: {"type":"error","error":{"type":"api_error","message":"Upstream request failed."},"request_id":"req_1f2e3d4c5b6a7988a1b2c3d4e5f60718"}

/responses（OpenAI Responses）：

Text
event: error
data: {"type":"error","code":"provider_error","message":"Upstream request failed.","param":null}

错误码

code（OpenAI 形态）与 error.type（Anthropic 形态）是稳定的，可安全用于 分支判断；message 文本不是——它可能随时变化，不作兼容承诺。

HTTP 状态码codeOpenAI typeAnthropic type含义
400invalid_requestinvalid_request_errorinvalid_request_error请求格式有误
401invalid_api_keyauthentication_errorauthentication_errorAPI 密钥缺失或无效
402insufficient_creditsbilling_errorbilling_error预付余额不足
403permission_deniedpermission_errorpermission_error密钥无权访问该模型或路径
404route_not_foundinvalid_request_errornot_found_error未知路径
404model_not_foundinvalid_request_errornot_found_error模型 id 不存在
405method_not_allowedinvalid_request_errorinvalid_request_error该路径不支持此 HTTP 方法
413request_too_largeinvalid_request_errorrequest_too_large请求体超出大小限制
429rate_limit_exceededrate_limit_errorrate_limit_error请求过多，参见 retry-after 响应头
502provider_errorupstream_errorapi_error上游 provider 请求失败
503overloadedservice_unavailable_erroroverloaded_errorGateway 并发处理已达上限，请稍后重试
503gateway_unavailableservice_unavailable_errorapi_error无法连接上游
504upstream_timeouttimeout_errorapi_error请求上传或上游响应超时

请用顶层 model 字段选择模型。通过 extra_body.model、models 或 route 选择上游模型的请求会返回 HTTP 400（invalid_request）。此规则也适用于 extra_body 内的 models 和 route、提供方或部署选择字段、api_key 或 extra_headers 中的 Authorization 等提供方凭据，以及回退模型列表。

SDK 建议

根据 code / error.type 与 HTTP 状态码做分支判断，不要依赖 message。 4xx 一般不应重试（429 除外，可在 retry-after 之后重试），5xx （502/503/504）可带退避重试。