错误码说明
天鸿智算 API 出现错误时会返回符合 OpenAI 协议规范的 JSON 错误体。本节列出常见 HTTP 状态码及对应排查建议。
错误响应格式
{
"error": {
"message": "Invalid API key provided",
"type": "invalid_request_error",
"code": "invalid_api_key"
}
}HTTP 状态码
| 状态码 | 含义 | 常见原因 | 处理建议 |
|---|---|---|---|
| 400 | 请求参数错误 | JSON 格式错误、必填字段缺失、参数取值越界 | 检查请求体结构与字段类型 |
| 401 | 未授权 | 未携带 API Key 或 Key 无效 | 核对 Authorization 请求头 |
| 403 | 禁止访问 | Key 无该模型权限、账户欠费、IP 受限 | 到控制台开通权限或充值 |
| 404 | 资源不存在 | 请求路径错误、模型名拼写有误 | 核对 URL 与 model 参数 |
| 413 | 请求体过大 | 上传图片/音频文件超过单次限额 | 压缩文件或拆分请求 |
| 429 | 请求过于频繁 | 超出 QPS 或额度限制 | 客户端做指数退避重试 |
| 500 | 服务内部错误 | 后端临时异常 | 稍后重试，持续异常请联系支持 |
| 502 / 503 / 504 | 网关/上游错误 | 后端模型服务繁忙或超时 | 稍后重试或更换模型 |
业务错误码
| code | 说明 |
|---|---|
invalid_api_key | API Key 无效或已禁用 |
insufficient_quota | 账户余额不足或额度已用尽 |
model_not_found | 指定的模型不存在或未开通 |
context_length_exceeded | 输入超过模型上下文长度限制 |
rate_limit_exceeded | 请求频率超过限制 |
content_filter | 输入或输出触发内容安全策略 |
对于 5xx 与 429 错误建议采用指数退避重试策略，初始等待 1s，每次翻倍，最多重试 5 次。