OpenAI 兼容接口常见错误排查

从 HTTP 状态、错误 code、request_id 和重试策略定位 OpenAI 兼容接口问题。

错误响应结构

所有错误响应都遵循以下统一结构（与 OpenAI 协议保持兼容）：

error envelopejson

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded for model deepseek-v4-pro",
    "param": null,
    "request_id": "req_01HZX3..."
  }
}

HTTP 状态对照

4xx 客户端错误

HTTP	code	含义	建议处理
400	`invalid_request_error` type: invalid_request_error	请求体不合法，例如缺少字段或字段类型错误。	修复请求结构后重试，不要无脑重试。
400	`context_length_exceeded` type: invalid_request_error	输入 token 超过模型 context_window 上限。	裁剪历史消息或换用 context 更大的模型；可以先调用 /v1/models 查 context_window。
400	`invalid_model` type: invalid_request_error	model 字段非法或当前账号不可用。	调用 /v1/models 列出可用模型并刷新本地缓存。
401	`invalid_api_key` type: authentication_error	API Key 缺失、格式错误或已撤销。	检查环境变量与 Header；必要时在控制台重新生成。
403	`permission_denied` type: permission_error	当前 Key 没有调用该模型 / 该端点的权限。	在控制台为对应 Key 开通模型权限，或换一把更高权限的 Key。
404	`model_not_found` type: invalid_request_error	模型 ID 不存在或已下架。	回退到列表中的等价模型；同时刷新 /v1/models 缓存。
408	`request_timeout` type: timeout_error	上游模型在网关侧设定的超时窗口内未返回。	建议带退避的重试；流式请求可在客户端做断点续读。
409	`conflict` type: invalid_request_error	资源状态冲突，例如重复的 idempotency key。	更换 idempotency key 或确认上一次请求的最终状态后再处理。
413	`payload_too_large` type: invalid_request_error	请求体超过网关上限（含 base64 多模态内容）。	压缩或分片上传；图片/音频走对应的多模态接口。
422	`unprocessable_entity` type: invalid_request_error	语义合法但模型无法处理（例如违反 response_format 约束）。	检查 response_format / tools 定义。
429	`rate_limit_exceeded` type: rate_limit_error	触发账号 / Key / 模型级限速。	退避重试；尊重 Retry-After Header。具体上限以控制台显示为准。
429	`insufficient_quota` type: rate_limit_error	账户余额或额度不足。	在控制台充值或申请额度，不要重试。

400invalid_request_error
请求体不合法，例如缺少字段或字段类型错误。
建议：修复请求结构后重试，不要无脑重试。
400context_length_exceeded
输入 token 超过模型 context_window 上限。
建议：裁剪历史消息或换用 context 更大的模型；可以先调用 /v1/models 查 context_window。
400invalid_model
model 字段非法或当前账号不可用。
建议：调用 /v1/models 列出可用模型并刷新本地缓存。
401invalid_api_key
API Key 缺失、格式错误或已撤销。
建议：检查环境变量与 Header；必要时在控制台重新生成。
403permission_denied
当前 Key 没有调用该模型 / 该端点的权限。
建议：在控制台为对应 Key 开通模型权限，或换一把更高权限的 Key。
404model_not_found
模型 ID 不存在或已下架。
建议：回退到列表中的等价模型；同时刷新 /v1/models 缓存。
408request_timeout
上游模型在网关侧设定的超时窗口内未返回。
建议：建议带退避的重试；流式请求可在客户端做断点续读。
409conflict
资源状态冲突，例如重复的 idempotency key。
建议：更换 idempotency key 或确认上一次请求的最终状态后再处理。
413payload_too_large
请求体超过网关上限（含 base64 多模态内容）。
建议：压缩或分片上传；图片/音频走对应的多模态接口。
422unprocessable_entity
语义合法但模型无法处理（例如违反 response_format 约束）。
建议：检查 response_format / tools 定义。
429rate_limit_exceeded
触发账号 / Key / 模型级限速。
建议：退避重试；尊重 Retry-After Header。具体上限以控制台显示为准。
429insufficient_quota
账户余额或额度不足。
建议：在控制台充值或申请额度，不要重试。

5xx 服务端错误

HTTP	code	含义	建议处理
500	`internal_error` type: api_error	网关或上游内部错误。	指数退避重试，超过 3 次仍失败建议人工排查并提供 request id。
502	`upstream_error` type: api_error	上游 provider 返回非预期错误。	可重试；如果稳定复现，换备用模型或联系支持。
503	`service_unavailable` type: api_error	上游容量受限，常见于热门模型瞬时拥塞。	退避重试；启用智能路由的账号一般会自动切换备用 provider。
504	`gateway_timeout` type: api_error	网关到上游超时。	同 408；如果是流式请求注意检查 last-event-id。

500internal_error
网关或上游内部错误。
建议：指数退避重试，超过 3 次仍失败建议人工排查并提供 request id。
502upstream_error
上游 provider 返回非预期错误。
建议：可重试；如果稳定复现，换备用模型或联系支持。
503service_unavailable
上游容量受限，常见于热门模型瞬时拥塞。
建议：退避重试；启用智能路由的账号一般会自动切换备用 provider。
504gateway_timeout
网关到上游超时。
建议：同 408；如果是流式请求注意检查 last-event-id。

重试策略

立即失败：4xx 中除429 / 408 外，多数无需重试。
指数退避：429 / 5xx 推荐 base = 500ms 起，乘 2，最大 8s，并尊重响应 HeaderRetry-After。
幂等性：可选发送Idempotency-Key Header（UUID v4），重试时复用同一个 key，网关会避免重复扣费。
退路模型：在客户端定义一个备选模型列表，遇到 model_not_found / service_unavailable 时降级。

排障：使用 request_id

每次响应（成功或失败）都会带上 X-Request-Id Header，失败响应体也包含 error.request_id。提交工单或在 FAQ提到的任何排查流程中都需要这个 ID——它能让我们直接定位到具体一次请求的链路日志。

问题是什么

OpenAI 兼容只保证请求形状相近，不代表所有模型支持相同参数或工具协议。排障应先读取 HTTP 状态、错误 code 和 request_id。

最短可用配置

.envbash

Base URL: https://api.gpt88.cc/v1
Header: Authorization: Bearer <API_KEY>
Path: /chat/completions
Model: 从当前模型目录复制

API Key 只放在服务端环境变量或密钥管理器中，不要提交到 Git、截图、浏览器前端或公开 issue。

完整示例（curl / Python / Node.js）

request.shbash

curl https://api.gpt88.cc/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-sol","messages":[{"role":"user","content":"返回 OK"}],"max_tokens":32}'

request.pypython

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.getenv("OPENAI_BASE_URL", "https://api.gpt88.cc/v1"),
)
response = client.chat.completions.create(
    model=os.getenv("OPENAI_MODEL", "gpt-5.6-sol"),
    messages=[{"role": "user", "content": "返回 OK"}],
    max_tokens=32,
)
print(response.choices[0].message.content)

request.mjsjavascript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL ?? "https://api.gpt88.cc/v1",
});
const response = await client.chat.completions.create({
  model: process.env.OPENAI_MODEL ?? "gpt-5.6-sol",
  messages: [{ role: "user", content: "返回 OK" }],
  max_tokens: 32,
});
console.log(response.choices[0].message.content);

常见错误

400 invalid_request_error：检查 JSON、必填字段和模型支持的参数。
401 authentication_error：检查 Key 和 Bearer 格式。
404：检查 /v1 前缀、资源路径和模型精确名称。
429：降低并发并设置最大重试次数。
500/502/503：保存 request_id、时间和模型后再提交最小复现。

价格和计费说明

成功请求按人民币余额、模型、分组倍率和输入输出用量结算；图片与视频可能使用独立计费项，不要仅按 HTTP 状态自行推算扣费。

可选分析设置