错误 · Tokener

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

非流式错误

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

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

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

Anthropic 形态的路径（/messages）：

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

流式错误

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

/chat/completions（OpenAI Chat Completions）：

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

/messages（Anthropic Messages）：

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

/responses（OpenAI Responses）：

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

错误码

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

HTTP 状态码	`code`	OpenAI `type`	Anthropic `type`	含义
400	`invalid_request`	`invalid_request_error`	`invalid_request_error`	请求格式有误
401	`invalid_api_key`	`authentication_error`	`authentication_error`	API 密钥缺失或无效
402	`insufficient_credits`	`billing_error`	`billing_error`	预付余额不足
403	`permission_denied`	`permission_error`	`permission_error`	密钥无权访问该模型或路径
404	`route_not_found`	`invalid_request_error`	`not_found_error`	未知路径
404	`model_not_found`	`invalid_request_error`	`not_found_error`	模型 id 不存在
405	`method_not_allowed`	`invalid_request_error`	`invalid_request_error`	该路径不支持此 HTTP 方法
413	`request_too_large`	`invalid_request_error`	`request_too_large`	请求体超出大小限制
429	`rate_limit_exceeded`	`rate_limit_error`	`rate_limit_error`	请求过多，参见 `retry-after` 响应头
502	`provider_error`	`upstream_error`	`api_error`	上游 provider 请求失败
503	`overloaded`	`service_unavailable_error`	`overloaded_error`	Gateway 并发处理已达上限，请稍后重试
503	`gateway_unavailable`	`service_unavailable_error`	`api_error`	无法连接上游
504	`upstream_timeout`	`timeout_error`	`api_error`	上游响应超时

SDK 建议

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