API 错误指南

本页说明各兼容 API 格式通用的错误处理方式。具体端点支持哪些状态码，以该端点“返回响应”中的状态码 Tab 为准；本页不会替代端点级响应示例。

HTTP 状态码

状态码说明

HTTP 状态码（15 个）
HTTP 状态码含义常见原因处理建议
200 OK请求成功请求已正常处理读取响应正文
201 Created资源创建成功创建任务或其他资源的端点返回新资源保存返回的资源标识
202 Accepted请求已接受异步任务已提交，尚未完成使用任务 ID 查询任务状态
400 Bad Request请求无效JSON 格式错误、缺少必填字段、参数值无效或 service_tier 不允许根据错误字段修正请求后再发送
401 Unauthorized认证失败API Key 缺失、错误、过期、撤销，或认证请求头格式错误检查 Authorization、x-api-key 或 x-goog-api-key
403 Forbidden禁止访问账户、项目、模型或来源区域没有访问权限检查账户、项目、模型和区域权限
404 Not Found资源不存在模型、任务 ID、资源 ID 或请求路径不存在检查 URL、模型名和资源 ID
408 Request Timeout请求超时客户端或网关等待响应超时确认请求是否已产生结果，再有限重试
409 Conflict请求冲突资源状态与当前操作不匹配根据错误信息刷新资源状态
422 Unprocessable Entity内容无法处理请求格式正确，但字段值或字段组合无法通过校验根据 error.param 修正字段
429 Too Many Requests速率或额度受限请求/Token 速率过高、余额耗尽、项目或组织额度达到上限优先遵循 Retry-After；额度类错误需先补充额度或提高限制
500 Internal Server Error服务内部错误网关或上游服务发生临时异常短暂等待后使用指数退避重试
502 Bad Gateway上游响应无效网关未收到有效上游响应短暂等待后重试，并记录请求 ID
503 Service Unavailable服务暂时不可用模型过载、维护或上游暂时不可用遵循 Retry-After（如有）后重试
504 Gateway Timeout上游响应超时网关等待模型或上游服务响应超时减小请求规模并有限重试

OpenAI 官方错误指南明确列出 400、401、403、429、500 和 503；其中 429 可能表示速率限制、余额耗尽或组织/项目限制，不能一概通过重试解决。详情参见 OpenAI API 错误码文档。

OpenAI 兼容错误响应

OpenAI 格式通常返回以下错误对象：

{
  "error": {
    "message": "Missing required parameter: messages",
    "type": "invalid_request_error",
    "param": "messages",
    "code": null
  }
}

排查时优先查看 error.message；error.type 用于判断错误类别，error.param 指出相关请求字段，error.code 可能提供更具体的额度或上游错误代码。

Anthropic 兼容错误响应

Claude Messages 格式使用 Anthropic 错误对象：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "请求参数无效"
  }
}

使用 Anthropic 格式时，应同时检查 HTTP 状态码、error.type 和 error.message。x-api-key 认证失败或缺少必需的 anthropic-version 时，通常先修正请求头，不要重复重试原请求。

Gemini 兼容错误响应

Gemini 原生格式使用 Google 风格错误对象：

{
  "error": {
    "code": 400,
    "message": "请求参数无效",
    "status": "INVALID_ARGUMENT"
  }
}

Gemini 客户端应读取 error.code、error.status 和 error.message。其中 error.code 通常与 HTTP 状态码一致；是否返回额外字段，以实际网关响应为准。

results matching ""

    No results matching ""