错误码 — U-Token 通用币 Docs

不同接口族使用的错误结构并不完全相同。网关会根据 LLM 上游错误的可读信息进行分类：仅上游以非 2xx 返回的号池类基础设施故障会收敛为 HTTP 424 中性错误，不向调用方暴露供应商细节和内部地址；其他上游非 2xx 保留原状态码，并按调用协议保留可公开的错误语义（上游未给 type 时为 upstream_error；上游错误体不是 JSON 时不透出正文，message 为 bad response status code <状态码>，type 与 code 为 bad_response_status_code；Anthropic Messages 的 message 末尾附带 (request id: …)）；上游以 HTTP 200 返回的错误正文（流式时为首个内容前的错误事件）：OpenAI Chat Completions 与 Responses 的流式请求、以及 Gemini 原生端点，按上游原样返回 HTTP 200 和上游正文；OpenAI Chat Completions 与 Responses 的非流式请求返回 HTTP 200 与 {"error": {...}}；Anthropic Messages 返回 HTTP 500。收到 HTTP 200 时请检查响应体或流中的 error。

LLM 与 Responses 端点

网关自身生成的错误通常使用：

{
  "error": {
    "message": "Missing model",
    "type": "model_not_found"
  }
}

常见类型包括 invalid_request_error、model_not_found、authentication_error、insufficient_quota、rate_limit_error、api_error 和 internal_error。

HTTP 402（insufficient_quota）会在 code 中说明原因：

`code`	含义	处理办法
`insufficient_balance`	余额不足，且没有可用的授信额度	充值。
`credit_line_exhausted`	余额不足，授信额度也已用完	充值。
`credit_line_not_allowed`	余额不足，且当前模型在当前渠道下不能使用授信额度，`message` 中会写明模型与渠道	充值，或改用可以使用授信的模型或渠道。
`key_limit_reached`	这把 Key 达到消费上限	调整 Key 限额，或改用其他 Key。

当 LLM 上游报告号池类基础设施故障时，网关会返回 HTTP 424，并按调用方协议返回中性的错误结构。可公开错误消息中的模型标识一律以公开模型 ID 呈现。OpenAI Chat Completions 与 Responses 使用：

{
  "error": {
    "code": "provider_error",
    "message": "Provider error (request id: aitk-12345678)",
    "type": "api_error"
  }
}

Anthropic Messages 使用 { "type": "error", "error": { "type": "api_error", "message": "..." } }；Gemini 使用 { "error": { "code": 424, "message": "...", "status": "FAILED_PRECONDITION" } }。号池故障的上游诊断详情只保留在服务端日志中。网络失败和流读取失败同样使用中性的提供方错误；已经建立的流会按对应协议发送终止 SSE 事件。

其它上游非 2xx（含非 JSON 正文、上游 401/402/403、限流与 5xx）保留原 HTTP 状态码。OpenAI Chat Completions 与 Responses 会保留 message 以及上游提供且协议支持的 type、code、param；Anthropic 返回原生错误结构；Gemini 返回原生 { "error": { "code", "message", "status" } } 结构。畸形、空或缺少预期字段的错误体会使用安全的协议兼容回退，并对消息脱敏。

媒体异步任务端点

/v1/router/... 的路由级错误通常使用：

{
  "code": 402,
  "message": "Insufficient balance. Top up to continue.",
  "task_id": ""
}

媒体任务接口不使用 LLM 账户限流，也不再占用已退役的按 Key / 按 IP 共享额度。

OpenAI 兼容图片端点

/v1/images/generations 与 /v1/images/edits 使用：

{
  "error": {
    "message": "Only n=1 is supported",
    "type": "invalid_request_error",
    "code": null
  }
}

还可能返回 authentication_error、insufficient_quota、rate_limit_error、api_error 或 timeout_error。

HTTP 状态码参考

状态码	常见类型 / 情况	处理办法
`400`	`invalid_request_error` 或 `model_not_found`	检查 JSON 与必填字段，并使用当前 Key 的 `GET /v1/models` 返回 ID 和端点；同时检查渠道与模型权限。
`401`	`authentication_error`	检查 API Key 是否存在、有效且格式正确。
`402`	`insufficient_quota`	充值，或改用未达到消费上限的 Key。
`403`	媒体模型未向当前调用方开放	检查模型权限、控制台价格页和模型列表。
`404`	媒体任务不存在，或不属于当前买家	检查 `task_id`，并使用同一买家的 API Key。
`409`	媒体任务缺少上游 id，或终态冲突	重新查询任务；状态持续异常时联系支持。
`424`	LLM 端点返回 `api_error`，且 `error.code=provider_error`	记录请求 ID；仅在业务层使用指数退避与抖动进行受控重试。
`429`	LLM 账户限流、上游限流或重复请求保护	`account_rpm_limit` 按 `RateLimit-*` 退避，`account_concurrency_limit` 按 `Retry-After` 退避；重复请求保护不带这两组响应头。
`5xx`	`upstream_error`、`api_error`、`internal_error` 或 `timeout_error`	对可恢复错误进行重试；图片接口返回 `504` 时应继续轮询 `task_id`，因为任务仍在运行。

如果上游流在 HTTP 200 已提交后读取失败，状态码无法再改为 424。下游连接仍可写时，网关会按当前协议追加且只追加一次携带请求 ID 的 provider_error 事件，不发送正常完成标记，随后关闭流且不暴露底层异常。客户端或传输连接已经断开时无法再送达错误事件，只保留内部失败日志。客户端应将收到错误事件，或未收到协议完成事件就中断的流，均视为失败响应；联系支持时请提供事件正文或 X-AIToken-Request-Id / X-OneAPI-Request-Id 响应头中的请求 ID。

LLM 与 Responses 端点

媒体异步任务端点

OpenAI 兼容图片端点

HTTP 状态码参考

On this page