错误码

当请求失败时，接口会返回 HTTP 状态码和错误对象。先看状态码，再看 error.message。

错误响应格式

OpenAI / Anthropic 兼容接口常见格式：

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

Gemini 原生接口常见格式：

{
  "error": {
    "code": 401,
    "message": "Invalid API key",
    "status": "UNAUTHENTICATED"
  }
}

常见状态码

HTTP 状态码	常见含义	排查方式
400	请求体错误或 query 参数不允许	检查 JSON、参数类型；Gemini 不要用 api_key query
401	鉴权失败	检查 API Key 是否完整、是否原样复制、是否被删除
403	无权限	检查令牌分组、模型权限、账号状态、余额或订阅
404	地址、接口或模型不存在	检查 Base URL、接口路径、模型名、分组平台
408	请求超时	缩短输入、重试或换模型
429	速率限制或额度耗尽	降低并发、等待重试、检查额度
500	上游或网关异常	记录请求 ID，稍后重试
502 / 503 / 504	上游暂不可用	换模型或等待恢复

401：Invalid API key

检查：

1. Key 是否按控制台显示原样复制。系统生成的 Key 通常以 sk- 开头；自定义 Key 以控制台显示为准。
2. Key 后面是否加了 #claude、#gemini、:openai、/v1 等不存在的后缀。
3. Authorization 是否写成 Bearer <API_KEY>。
4. Key 前后是否有空格、换行或中文引号。
5. Key 是否已经在控制台删除或过期。

400：api_key in query deprecated

主 /v1 接口不接受 URL query 传 Key。请改成请求头：

Authorization: Bearer sk-your-api-key

Gemini /v1beta 推荐使用：

x-goog-api-key: sk-your-api-key

404：Not Found

最常见原因是 Base URL 写错。

OpenAI Compatible 正确写法：

https://portdan.com/v1

不要写：

https://portdan.com/v1/chat/completions

Claude Code 正确写法：

https://portdan.com

不要把 ANTHROPIC_BASE_URL 写成：

https://portdan.com/v1/messages

Gemini CLI 正确写法：

https://portdan.com

OpenCode Gemini 或直接 HTTP 才使用：

https://portdan.com/v1beta

429：Rate limit

429 通常与并发、速率、余额或令牌限额有关。建议：

• 降低并发。
• 对 429 做指数退避重试。
• 检查令牌限额。
• 检查账号余额和模型分组额度。

提交工单时请带上

• 请求时间。
• 使用的客户端和协议类型。
• Base URL。
• 使用的模型名。
• HTTP 状态码。
• 错误信息。
• 不要提供完整 API Key；最多提供前后各 4 位用于定位。