常见错误排查启玥 API 使用教程
接口请求错误快速查阅，定位报错原因与处理方案
快速对照表
| HTTP | 错误码 | 含义 | 可重试 | 解决办法 |
|---|---|---|---|---|
| 400 | invalid_request_error | 请求参数错误 | 否 | 检查请求体 JSON 与必填字段；messages / model 写法需与官方示例一致 |
| 401 | invalid_api_key | API Key 无效 | 否 | 重新复制密钥，确认前后无空格；必要时创建新密钥 |
| 402 | insufficient_quota | 余额不足 | 否 | 到控制台核对余额与有效期；充值或兑换后重试 |
| 403 | permission_denied | 无访问权限 | 否 | 确认密钥所属分组包含该模型，并核对接口权限 |
| 404 | model_not_found | 模型不存在 | 否 | 从模型广场复制完整模型 ID；确认当前分组支持 |
| 408 | request_timeout | 请求超时 | ✓ | 直接重试即可；持续超时可换分组或换模型 |
| 413 | context_length_exceeded | 上下文超限 | 否 | 缩短输入或分块提交；确认模型的上下文上限 |
| 429 | rate_limit_exceeded | 速率限制 | ✓（按 Retry-After） | 按 Retry-After 等待后重试；降低并发或分批请求 |
| 500 | internal_server_error | 服务器错误 | ✓ | 重试一次；连续出现时保留请求 ID 联系售后 |
| 502 / 503 | service_unavailable | 上游不可用 | ✓ | 上游临时不可用，稍后重试；可切换同档备用模型 |
| 504 | gateway_timeout | 网关超时 | ✓ | 减小 max_tokens 或改用流式输出；持续出现时联系售后 |
| 401 | account_deactivated | 账号已停用 | 否 | 联系售后核实账号状态；确认是否有违规使用记录 |
| 402 | billing_hard_limit_reached | 达到消费上限 | 否 | 在控制台提高消费上限，或等待限额周期重置 |
| 429 | concurrency_limit_exceeded | 并发超限 | ✓ | 降低并发或分批提交；按 Retry-After 提示重试 |
| 503 | model_overloaded | 模型过载 | ✓ | 稍后重试，或切换同档位的备用模型 |
| 524 | origin_timeout | 源站响应超时 | 否 | 长文任务改用流式输出；减少单次输出长度 |
详细错误处理表
| 提示或状态码 | 常见原因 | 处理方法 |
|---|---|---|
| 401 | 密钥为空、复制不完整或已失效 | 重新复制密钥，确认没有多余空格；必要时创建新密钥 |
| 403 | 密钥分组或模型权限不匹配 | 检查密钥所属分组和模型支持范围 |
| 404 | 接口地址填写错误 | 检查是否重复添加了 /v1，或误把 Base URL 与完整 Endpoint 混用 |
| 429 | 余额、并发、频率限制或上游繁忙 | 查看账户状态，稍后重试；持续出现时联系平台处理 |
| model not found | 模型 ID 拼写错误或当前分组不支持 | 从模型广场复制完整模型 ID |
| 浏览器提示 HTTP 不安全 | 使用了 http:// | 统一改成 https://api.qiyue999.top |