错误码与排查指南
本文用于定位 AnideaAI 接口调用失败原因，适用于 https://anideaai.com/v1 与控制台相关接口。
错误响应格式
AnideaAI 对外返回 OpenAI 兼容结构，核心字段在 error 对象中：
{
"error": {
"code": "RATE_MODEL_LIMIT",
"message": "该模型请求频率已达上限（1分钟内100次）",
"type": "rate_limit_error",
"request_id": "req_xxx",
"trace_id": "req_xxx"
}
}
字段说明：
code：平台业务错误码（用于程序分支判断）message：给用户看的提示type：兼容错误类型（如authentication_error、rate_limit_error）request_id/trace_id：问题追踪编号，提工单时必须带上
HTTP 状态码说明
| 状态码 | 典型原因 | 建议处理 |
|---|---|---|
| 400 | 请求体格式错误、参数缺失或非法、内容被策略拦截 | 检查请求 JSON、必填字段、模型名和内容合规性 |
| 401 | API Key 缺失、无效、过期、登录态失效 | 检查 Authorization，确认 Key 状态 |
| 403 | 账号/Key 权限不足、IP 不在白名单、额度不足 | 检查分组权限、模型权限、账户余额与 Key 限额 |
| 404 | 模型不存在、接口路径错误 | 先调用 /v1/models 确认可用模型 |
| 413 | 请求体太大 | 减少输入内容或分片上传 |
| 429 | 命中频率限制、并发上限、订阅窗口上限 | 读取 error.code，按限流策略重试 |
| 500 | 平台内部异常、扣费流程异常 | 记录 request_id 后重试，必要时联系客服 |
| 501 | 接口暂未实现 | 改用已支持接口 |
| 502 | 上游服务失败、渠道异常 | 短暂退避后重试，必要时切换模型 |
| 503 | 服务繁忙、渠道无可用实例 | 排队重试，避开高峰 |
| 504 | 上游超时 | 缩短输入、降低并发、重试 |
业务错误码（按类别）
以下是高频错误码与处理建议，覆盖了日常 90% 以上排查场景。
认证与权限
| 错误码 | 含义 | 处理建议 |
|---|---|---|
AUTH_TOKEN_MISSING | 未提供 API Key | 补充 Authorization: Bearer sk-xxx |
AUTH_TOKEN_INVALID | API Key 无效 | 检查是否复制错误、是否已删除 |
AUTH_TOKEN_EXPIRED | API Key 过期 | 更新过期时间或新建 Key |
AUTH_TOKEN_DISABLED | API Key 被禁用 | 在控制台启用或更换 Key |
AUTH_IP_RESTRICTED | 当前 IP 不在白名单 | 调整 Key 的允许 IP |
AUTH_PERMISSION_DENIED | 权限不足 | 检查账号角色或管理权限 |
AUTH_GROUP_FORBIDDEN | 无权访问当前分组 | 切换有权限分组或联系管理员授权 |
AUTH_2FA_REQUIRED | 登录需要两步验证 | 先完成 2FA 验证 |
额度与计费
| 错误码 | 含义 | 处理建议 |
|---|---|---|
QUOTA_USER_INSUFFICIENT | 账户总额度不足 | 充值或调整预算 |
QUOTA_TOKEN_INSUFFICIENT | 当前 Key 额度不足 | 提高 Key 配额或换 Key |
QUOTA_MONTHLY_5H_EXCEEDED | 5 小时窗口超限 | 等窗口恢复后再发起请求 |
QUOTA_MONTHLY_DAILY_EXCEEDED | 日额度超限 | 次日再试或调整计划 |
QUOTA_MONTHLY_WEEKLY_EXCEEDED | 周额度超限 | 下周窗口恢复后再试 |
QUOTA_MONTHLY_EXCEEDED | 月额度超限 | 下月恢复或升级计划 |
QUOTA_SUBSCRIPTION_EXPIRED | 订阅已过期 | 续费或重新购买计划 |
频率与并发
| 错误码 | 含义 | 处理建议 |
|---|---|---|
RATE_GLOBAL_LIMIT | 全局接口频率过高 | 降低请求速率，增加重试退避 |
RATE_MODEL_LIMIT | 模型请求频率过高 | 按分组限额降速，拆分流量 |
RATE_CONCURRENT_FULL | 当前并发已满 | 优先读取 Retry-After 后重试 |
UPSTREAM_RATE_LIMITED | 上游渠道限流 | 退避重试或切换可用模型 |
模型与路由
| 错误码 | 含义 | 处理建议 |
|---|---|---|
MODEL_NOT_FOUND | 模型不可用或不存在 | 调用 /v1/models 获取最新可用模型 |
MODEL_PERMISSION_DENIED | Key 无权访问该模型 | 调整 Key 模型白名单 |
CHANNEL_NO_AVAILABLE | 无可用渠道 | 稍后重试，必要时联系平台排查 |
CHANNEL_ALL_FAILED | 渠道全部失败 | 退避后重试或切换模型 |
请求与系统
| 错误码 | 含义 | 处理建议 |
|---|---|---|
REQUEST_PARAM_MISSING | 缺少必要参数 | 对照接口文档补全字段 |
REQUEST_PARAM_INVALID | 参数值非法 | 检查字段类型与可选范围 |
REQUEST_BODY_TOO_LARGE | 请求体过大 | 压缩/拆分输入 |
SYSTEM_INTERNAL_ERROR | 服务内部错误 | 使用 request_id 提交问题并重试 |
SYSTEM_SERVICE_UNAVAILABLE | 服务暂不可用 | 等待恢复后重试 |
常见排查路径
1. 收到 401/403
- 先确认 Key 是否启用、过期、额度是否足够。
- 再确认 Key 的模型权限、分组权限、IP 白名单。
- 若是控制台接口，检查登录态和账号状态。
2. 收到 429
- 先看
error.code：是全局限流、模型限流、并发满，还是订阅窗口超限。 - 若响应头有
Retry-After，按该秒数后再重试。 - 加入指数退避和随机抖动，避免所有请求同一时刻回冲。
3. 收到 5xx（500/502/503/504）
- 记录
request_id。 - 按 1s、2s、4s 做最多 3 次重试。
- 仍失败时保留请求参数摘要和
request_id提交工单。