错误文档

常见 API 错误码、含义与处理建议。调用 /v1/chat/completions（或 api/relay.php）时请根据 HTTP 状态码与返回的 error.message 排查。

HTTP 状态码与错误说明

状态码	常见 message	含义与处理建议
400	无效的请求体 / Model is required / 模型 xxx 不受支持	请求 JSON 格式错误、缺少 `model` 字段，或所选模型不在支持列表中。请检查请求体与模型名称。
401	缺少认证凭证 / 无效的 API Key 或登录令牌 / 令牌无效或已过期	未携带 `Authorization: Bearer <key>`，或 Key / 登录令牌错误、已过期。请到「令牌管理」核对 Key，或重新登录。
402	余额不足，请先充值或兑换余额	账户余额不足以支付本次调用。请前往「充值中心」充值或使用兑换码。
403	需要管理员权限 / 需要服主权限 / 账号被封禁或冻结	当前身份无权执行该操作，或账号被限制。普通用户请勿调用管理接口；若账号异常请联系管理员。
404	无效的请求路径或方法	URL 或 HTTP 方法不正确。聊天/补全请使用 `POST /v1/chat/completions`。
429	操作过快 / 请求过于频繁	触发频率限制（例如短时间内创建过多密钥）。请稍后重试，并避免短时间大量并发。
500	保存失败 / 服务器内部错误	服务端异常。可稍后重试；若持续出现请联系管理员并提供时间与请求 ID（如有）。
503	上游服务不可用 / 上游 HTTP 状态码 …	上游模型服务暂时不可用或返回错误。请稍后重试；可在「服务状态」页查看上游连通情况。

排查建议：
1. 确认请求头包含 Authorization: Bearer sk-你的密钥 与 Content-Type: application/json。
2. 确认 model 为「模型商城」中支持的 ID。
3. 查看「仪表盘 / 令牌管理」中的余额与密钥状态。
4. 若返回非 JSON 或网关错误页，请检查反向代理是否透传了 Authorization 头（部分环境可同时带 X-Auth-Token）。

错误响应格式示例

{
  "error": {
    "message": "余额不足，请先充值或兑换余额"
  }
}

客户端应根据 HTTP 状态码与 error.message 做提示，而不是仅依赖状态码数字。