错误码

GPUShare gateway 返回的错误响应协议自适配 —— OpenAI Chat 端点返 {"error":{...}},Anthropic Messages 端点返 {"type":"error","error":{...}},Gemini Native 端点返 {"error":{"code","status",...}}。

错误码语义跨协议一致,本页用 HTTP status 索引。

401 Unauthorized

`invalid_api_key`

API Key 无效或已被撤销。

OpenAI 风格:

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

排查:

检查 Key 是否复制完整 (sk-gpushare- + 32 字符,共 44 字符)
检查 Key 是否在 model.dflop.top/keys 还存在 (未删)
检查 Key 是否过期 (默认不过期,除非你设置了 expires_at)

`missing_api_key`

请求没带 API Key。

排查: 见鉴权,三种鉴权方式任选一种附上 Key。

403 Forbidden

`model_not_allowed`

Key 的 allowed_models 配置不含请求的 model。

排查: 在 model.dflop.top/keys 编辑 Key,把目标 model 加进 allow-list,或新建一把 allow-all Key。

`forbidden`

通用 403。常见于跨账号访问其他用户的资源。

404 Not Found

`model_not_found`

请求的 model ID 不在 catalog,或该 model 不支持当前协议端点。

OpenAI 风格:

{"error": {"message": "Model 'claude-3.5-opus' not found", "type": "invalid_request_error", "code": "model_not_found"}}

排查:

拼写校验 —— claude-sonnet-4-5-20250929 含日期后缀必须完整
完整模型列表比对一遍
协议端点匹配 —— Gemini 模型不能走 /v1/messages,详见兼容矩阵

412 Precondition Failed

`quota_exhausted`

API Key 配额耗尽 (quota_used >= quota_total)。

OpenAI 风格:

{"error": {"message": "Key quota exhausted (used: $5.00 / total: $5.00)", "type": "insufficient_quota", "code": "quota_exhausted"}}

排查:

model.dflop.top/keys 给 Key 充值
或在控制台创建新 Key

注: Key 的 quota_total 跟账户余额是独立预算,Key 用完不影响账户余额,反之亦然。

`input_too_large`

请求的 input tokens 估算超过 Key 的 max_input_tokens_per_request 上限 (默认 50K)。

排查: 缩减 messages 历史 / system prompt,或在控制台调高 Key 的上限。

429 Too Many Requests

`rate_limit_exceeded`

短时间内并发请求过高 (上游通道速率限制)。GPUShare 自身没硬 QPS,这条来自上游。

排查:

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

500 Internal Server Error

`internal_error`

gateway 自身异常。罕见。

排查: 重试 1-2 次;如持续,通过 community 反馈,附上响应体的 request_id 字段。

502 Bad Gateway

`upstream_error`

上游模型 provider 返回了非 200 但非速率限制的错误。

OpenAI 风格:

{"error": {"message": "Upstream returned 500", "type": "upstream_error", "code": "upstream_error"}}

排查:

重试 (上游偶尔抖动)
切换 model (路由到不同上游通道)

`bltcy_5xx_sanitized`

中转 channel 上游 5xx,gateway 把原始错误体清洗后回传 (避免泄漏中转层细节)。语义同 upstream_error,处理方式一致。

503 Service Unavailable

`no_channel_available`

请求的 model 当前所有上游通道都处于 disabled / unhealthy 状态。

排查:

等几分钟重试 (gateway 健康检查每分钟标记通道)
切换 model
持续不可用通过 community 反馈

504 Gateway Timeout

`upstream_timeout`

上游响应超时 (120s 硬上限)。常见于超长 reasoning 模型 + 复杂任务。

排查:

降 max_tokens
拆分任务为多次调用
用 stream: true —— 流式不受 120s 一次性返回限制,首 chunk 到达即建立连接

排查决策树

请求失败
├─ 401 → Key 问题 → 重生成 Key
├─ 403 → 权限问题 → 编辑 Key allow-list
├─ 404 → model 拼写 / 协议不匹配 → 查 [兼容矩阵]
├─ 412 → 配额问题 → 充值或扩 max_tokens 上限
├─ 429 → 上游限速 → 退避重试
├─ 5xx → 上游 / 网关问题 → 重试 1-2 次, 切 model
└─ 网络层 (无 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 的 request_id / X-Protocol-Translation 获得诊断信息。