错误码

本网关返回的错误响应协议自适配 —— 哪个协议端点收到请求,就用哪个协议的官方错误格式回包,SDK 可原生解析。

错误体形状 (三协议对照)#

OpenAI 形状 (/v1/chat/completions、/v1/responses、/v1/embeddings,以及 图像 / 视频端点):

{"error": {"message": "...", "type": "...", "code": "..."}}

Anthropic 形状 (/v1/messages):

{"type": "error", "error": {"type": "...", "message": "..."}}

Gemini 形状 (/v1beta/models/{model}:generateContent):

{"error": {"code": 402, "message": "...", "status": "RESOURCE_EXHAUSTED"}}

注意: 字符串 code 字段(如 quota_exceeded)只存在于 OpenAI 形状。Anthropic 错误体只有 type + message;Gemini 的 code 是数字 HTTP 状态码,枚举语义在 status 字段。用 Anthropic / Gemini SDK 时请按下表对应列做匹配。

错误码真值表#

Gemini 端点上 402 与 429 共用 status: "RESOURCE_EXHAUSTED",需用数字 code (402/429) 区分。

400 Bad Request#

gateway 自产错误大部分集中在 400 —— 客户最常撞到的就是下面四个。

model_not_found#

请求的 model id 不在 pricing 注册表。

OpenAI 形状:

{"error": {"message": "model `claude-3.5-opus` is not available", "type": "invalid_request_error", "code": "model_not_found"}}

排查:

1. 拼写校验 —— claude-haiku-4-5-20251001 含日期后缀必须完整
2. 完整模型列表 比对一遍;GET /api/v1/models/public 返回的条目里 callable=false 的占位 SKU 调用也会返回本错误
3. 注意: model id 存在但当前协议没有通道时,返回的是 503 no_channel_available,不是本错误,详见 兼容矩阵

model_not_allowed#

Key 的 allowed_models 白名单不含请求的 model。

排查: 在 model.dflop.top/keys 编辑 Key,把目标 model 加进 allow-list,或新建一把不限模型的 Key。注意这是 400 —— 不要按 403 写分支。

invalid_request#

请求体非法 (缺必填字段 / JSON 解析失败 / 字段类型不对)。按 message 提示修正请求体。

tool_not_supported#

请求带的工具 (如 web_search / image_generation) 被路由到不支持该工具的上游通道。

排查: 确认所选 model 支持该工具 (兼容矩阵),或去掉 tools 字段重试。

401 Unauthorized#

invalid_api_key#

401 只有这一个 code —— 不带 Key、Key 错、Key 被撤销、Key 过期、账号停用都返回它,靠 message 区分:

OpenAI 形状:

{"error": {"message": "authentication failed: invalid api key", "type": "authentication_error", "code": "invalid_api_key"}}

排查:

1. 检查 Key 是否复制完整 —— 格式是 sk-gpushare- + 64 位十六进制,共 76 字符
2. 检查 Key 是否在 model.dflop.top/keys 还存在;Key 可在详情页随时重新查看完整值 (服务端加密存储),不确定就重新复制一遍
3. 检查鉴权方式 —— 四种回退任选: x-api-key / x-goog-api-key / ?key= query / Authorization: Bearer,详见 鉴权
4. 例外: GET /v1/models 只认 Authorization: Bearer 和 x-api-key 两种 header,不支持 ?key= —— 用 query 鉴权调它会 401

402 Payment Required#

quota_exceeded#

账户余额耗尽。计费走统一钱包 —— 所有 API Key 共享同一账户余额,Key 本身没有独立预算池,余额耗尽时所有 Key 同时失效,「新建 Key」不会带来新额度。

OpenAI 形状:

{"error": {"message": "quota exceeded: used 0.30 of 0.30 USD", "type": "insufficient_quota", "code": "quota_exceeded"}}

Anthropic 形状: "type": "billing_error";Gemini 形状: "status": "RESOURCE_EXHAUSTED" (数字 code 为 402)。

排查:

1. 注册自带 $0.30 体验额度;烧完后去主站 dflop.top/dashboard/billing 充值 (Stripe,最低 $1,与 model.dflop.top 同账号 SSO 共享余额)
2. 在控制台核对余额与用量,确认是哪类调用消耗大 —— chat/embeddings 按 token,图像按张,视频按秒,详见 图像 / 视频 / Embedding API

403 Forbidden#

permission_denied#

仅上游透传 —— gateway 自身不产生任何 403。看到 403 说明上游 provider 拒绝了这次调用 (内容策略 / 区域限制等),message 是上游原话。

排查: 切换 model 让请求路由到不同上游;持续出现可通过 community 反馈。

429 Too Many Requests#

rate_limit_exceeded#

上游通道限流透传。本网关自身没有硬性 QPS 限制,这条来自上游。

排查:

1. 客户端加指数退避重试 (1s → 2s → 4s)
2. 或切换 model 让 gateway 路由到不同上游通道

500 Internal Server Error#

internal_error#

gateway 自身异常。罕见。

排查: 重试 1-2 次;如持续,通过 community 反馈,附上时间戳 + model id + 完整错误响应体 (如有,加上 Cloudflare cf-ray 响应 header)。错误响应里没有 request_id 字段,不用找。

502 Bad Gateway#

upstream_unreachable#

上游连接失败 (DNS / TCP / TLS 层面够不着上游)。只有这种场景固定返回 502 —— 上游自身返回的 5xx 走 原状态码透传,不会被改写成 502。

排查: 重试 (上游偶尔抖动),或切换 model。

503 Service Unavailable#

no_channel_available#

请求的 model 在当前协议端点下没有可用上游通道 —— 包括所有通道 disabled / unhealthy,也包括该 model 本身不支持这个协议 (比如用 /v1/messages 调一个只有 OpenAI 协议通道的 model)。

排查:

1. 先查 兼容矩阵 确认 model × 协议组合受支持
2. 切换 model
3. 持续不可用通过 community 反馈。gateway 健康探测每 6 小时一轮 (部署后有一次启动 warmup),所以「等几分钟重试」对 unhealthy 通道基本无效,直接切 model 更快

504 Gateway Timeout#

upstream_timeout#

上游响应超时。各端点上游超时上限不同:

排查:

1. 降 max_tokens 或拆分任务为多次调用
2. 用 stream: true 可以更早拿到首 token,但整条流仍受 180s 总时长上限约束 —— 流式不是不限时
3. 客户端 SDK 的 timeout 建议设 ≥ 200s,留出余量
4. 超长任务 (视频生成) 走异步提交 + 轮询,不受单请求超时影响,详见 图像 / 视频 / Embedding API

上游错误透传#

上游返回非 2xx 时,gateway 原状态码透传 (上游 500 → 响应 500,上游 429 → 响应 429),message 解包成上游原话,OpenAI 形状的 type / code 按状态码映射:

排查: 重试 1-2 次 (上游偶尔抖动),或切换 model 路由到不同上游通道。

流式中的错误#

流式请求一旦以 HTTP 200 开流,中途出错就无法再改状态码 —— 错误只能体现在流本身:

• 流提前终止: 上游中途失败时,gateway 不注入自己的错误帧,流直接结束 —— OpenAI SSE 不会收到 data: [DONE] 终止帧,最后一个 chunk 没有 finish_reason (Anthropic 流则缺 message_stop 事件)
• 上游错误帧透传: 如果上游在断流前发出协议内的错误事件 (如 Anthropic 的 event: error 帧),gateway 原样转发
• 例外 —— 内置工具路径: /v1/chat/completions 带 web_search / image_generation 内置工具的请求走专用通道,中途失败时 gateway 会合成一个错误 chunk ({"error":{"message":…,"type":"api_error","code":"upstream_error"}}) 再跟 data: [DONE] 收尾,详见 流式响应指南

客户端应对:

1. 不要只依赖连接关闭 —— 校验是否收到 data: [DONE] / finish_reason / message_stop,缺失即视为不完整流
2. 不完整流按失败处理,带退避重试

计费口径: 中断前已传输的部分按实际 usage 结算 (上游没来得及发 usage chunk 时,按已输出字符估算 output tokens),中断的 turn 不会重复扣费也不会免费。

排查决策树#

请求失败
├─ 400 → model 拼写 / Key allow-list / 请求体 / 工具不被通道支持
├─ 401 → Key 问题 → 控制台重新查看并复制 Key (76 字符), 核对鉴权 header
├─ 402 → 账户余额耗尽 → dflop.top/dashboard/billing 充值 (新建 Key 没用)
├─ 403 → 上游拒绝 (透传) → 切 model
├─ 429 → 上游限速 → 退避重试
├─ 503 → 当前协议无可用通道 → 查兼容矩阵 / 切 model
├─ 其余 5xx → 上游 / 网关问题 → 重试 1-2 次, 切 model
├─ 流式中断 (200 后) → 校验 [DONE] / finish_reason → 按失败重试
└─ 网络层 (无 HTTP 响应) → 检查防火墙 / DNS / TLS 是否到达 api.dflop.top

调试技巧#

打开 SDK 的 debug 模式看完整请求 / 响应:

# OpenAI Python SDK
import logging
logging.basicConfig(level=logging.DEBUG)

# Anthropic Python SDK
import os
os.environ["ANTHROPIC_LOG"] = "debug"

# curl 全量
curl -v -i https://api.dflop.top/v1/chat/completions ...

响应 header 的 X-Protocol-Translation 标注了这次请求走的跨协议翻译路径,排查协议相关问题时值得带上。错误响应体和 header 里没有 request_id;反馈问题时请附时间戳 + model id + 完整错误体 (+ Cloudflare cf-ray header)。