#错误码参考

本页列出模型调用网关源码声明的 33 个 HTTP 错误码，包括兜底分支。 message 当前主要为英文；中文含义和处理建议见下表。按 error.code 判断，不按文案匹配。 参数校验文案随字段变化，同一 code 可以有多个 message；源码存在不等于每个分支都已逐项实测。 资金 402 与错误契约修复须随对应版本发布后才在线上生效。

#错误结构

{
  "error": {
    "code": "model_not_found",
    "message": "The model 'TokenPostie-example-model' does not exist or is not available to this account.",
    "param": "model",
    "type": "invalid_request_error"
  }
}

#稳定错误码

#实际返回文案

下表为固定英文原文或参数模板。{model}、{seconds} 是运行时值，不是字面文本。 HTTP 错误对象的 param 无特定参数时为 null；参数校验可能返回字段路径。

#参数校验文案

这类文案不是额外稳定错误码；通常归入 400 / invalid_request_error 或 unsupported_parameter， Messages 的部分原生控制拒绝只有 error.type、message、param，没有独立 code。

全部显式输入校验文案与字段模板见 参数错误文案，由源码生成并校验一致性。

#类型与传输差异

OpenAI-compatible error.type 按类别区分：401 为 authentication_error，权限/实名为 permission_error，资金为 insufficient_quota，429 为 rate_limit_error，参数/模型不存在为 invalid_request_error，平台与上游服务故障为 server_error。

Messages 采用 {"type":"error","error":{"type":"...","message":"...","code":"..."}}： 401 对应 authentication_error；402/403 对应 permission_error；404 对应 not_found_error； 429 对应 rate_limit_error；5xx 对应 api_error；其他通常为 invalid_request_error。 流式错误在已开始的 HTTP 200 内发送终止事件，不再改变 HTTP 状态。

Responses 流式错误是扁平事件，例如：

event: error
data: {"type":"error","code":"upstream_rate_limited","message":"Upstream capacity is temporarily limited. Please retry later.","param":null,"sequence_number":3}

WebSocket 还有 invalid_json（消息无法解析）、unsupported_type（仅支持 chat 类型）、 missing_model（缺少模型）及 internal_error（内部处理失败）；这是消息内 code，不是 HTTP 状态。 gRPC 使用 gRPC status，并在 tokenpostie-error-code 元数据中保留平台 code；资金为 FAILED_PRECONDITION，鉴权为 UNAUTHENTICATED，限流为 RESOURCE_EXHAUSTED。

#上游错误边界

资金类错误从旧版 429 调整为 402，错误码和 OpenAI-compatible 错误类型保持稳定；402 是 TokenPostie 的平台约定。 402 不返回 Retry-After，补充资金前重试不会解决问题。429 只用于请求频率、Token 或并发限制。 Messages 资金拒绝返回 type: "error" 外层和 error.type: "permission_error"，并保留资金错误码。

TokenPostie 不会把上游原始错误 code、message、raw body、request ID 或网络异常 cause 直接返回给 API 用户或客户管理员。最终用户侧应使用 TokenPostie 的 error.code 做稳定处理。

流式响应已经开始后，最初的 HTTP 状态仍可能是 200。客户端还必须读取终止 SSE 事件：OpenAI-compatible 流使用 data: {"error": ...}，Responses 和 Anthropic 流使用 event: error。

#请求日志排障

请求失败时，先保留响应里的 request id 或客户控制台请求日志中的请求 ID，再按以下顺序排查：

所有 HTTP 响应通过 x-tokenpostie-request-id 返回平台生成的请求 ID，不使用客户或上游提供的 ID。

请求路径完全没有匹配路由时，框架默认 404 可返回 {"message":"Route GET:/path not found","error":"Not Found","statusCode":404}，不带统一 code。 这与异常处理器的 not_found 兜底分支不同。先检查 URL 和 HTTP 方法，不要把未知路径响应当成模型错误。

1. 在客户控制台打开请求日志，确认模型、API Key、项目、HTTP 状态和 error.code。
2. 如果是 model_not_found 或 model_access_denied，重新调用 GET /v1/models，只使用返回的模型 id。
3. 如果是 rate_limit_exceeded，按当前 API Key 的 RPM、TPM、QPM 限额降速。
4. 如果是 insufficient_quota 或 credit_limit_exceeded，检查余额、授信和付款状态。
5. 联系 TokenPostie 运营时只提供请求 ID、错误码和时间，不提供完整 API Key。

相关排障步骤见 排障与安全。 客户后台的登录、组织、API Key、发票和通知错误见 客户后台错误。