常见错误

401：认证失败

确认使用的是「API 密钥」页创建的 Key，并按协议选择 Authorization: Bearer、x-api-key 或 x-goog-api-key。不要使用控制台登录令牌。

403：没有权限

检查 Key 是否启用、分组是否允许目标平台/模型、余额或订阅是否有效，以及用户平台配额是否被禁用。

404：路径错误

最常见原因是 SDK 自动拼接路径，而 Base URL 又多写一层：

• OpenAI SDK：https://sub.nanlabapi.top/v1
• Claude Code：https://sub.nanlabapi.top
• Gemini SDK：通常 https://sub.nanlabapi.top/v1beta

429：限流或额度

可能来自 Key 并发/RPM、5 小时或日/周窗口、订阅配额或上游账号冷却。尊重 Retry-After，使用指数退避，不要无上限立即重试。

5xx 或连接中断

先在「用量」与错误记录中查请求时间、模型和状态码。流式请求应识别协议的失败终止事件。只对幂等或可安全重放的请求重试。

获取帮助前准备

提供时间（含时区）、请求路径、模型、HTTP 状态码和脱敏后的请求 ID。不要提供完整 Key、完整 prompt、参考图 base64、Cookie 或登录令牌。