错误码说明

根据 HTTP 状态码理解错误原因，并采用正确的修复、重试与支持流程。

成功响应使用 2xx。遇到失败时，同时记录状态码、错误对象、请求 ID 和时间，不要只保存错误文案。

HTTP 状态码

状态码	含义	常见原因	处理建议
`400`	请求错误	JSON 无效、缺少参数、类型错误或模型不支持参数。	检查请求体和目标模型能力，不要原样重试。
`401`	鉴权失败	密钥缺失、无效、已撤销或 Bearer 格式错误。	检查环境变量与请求头，必要时轮换密钥。
`402`	余额不足	账户可用余额不足。	查看账单与余额，充值后再请求。
`403`	权限不足	账户或密钥无权访问相关资源。	检查账户状态、模型权限与平台规则。
`404`	不存在	接口路径或模型标识错误。	核对 URL，从模型广场复制准确标识。
`408`	请求超时	网络不稳定或生成超过时间限制。	检查请求大小和超时配置，对安全请求有限重试。
`429`	请求过多	频率、并发或账户配额达到限制。	降低并发，使用队列和指数退避，必要时申请扩容。
`500`	内部错误	服务器或路由节点在处理后仍失败。	记录请求 ID 后有限重试；持续失败时联系支持。
`502`	上游异常	推理节点返回无效响应。	稍后重试并保留请求信息。
`503`	暂不可用	可用节点不足、维护或短时过载。	指数退避，查看平台公告或联系支持。
`504`	网关超时	上游节点未及时完成响应。	减少输入输出长度、调整超时并有限重试。

错误对象示例

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

具体错误字段可能随错误类型变化。客户端应允许新增字段，并在字段缺失时回退到 HTTP 状态码。

Python 异常处理

import openai

try:
    response = client.chat.completions.create(
        model="glm-5.1",
        messages=[{"role": "user", "content": "你好"}],
    )
except openai.AuthenticationError:
    print("API Key 无效或已撤销")
except openai.RateLimitError:
    print("请求过快，请退避后重试")
except openai.APITimeoutError:
    print("请求超时")
except openai.APIConnectionError:
    print("无法连接 API，请检查网络")
except openai.APIStatusError as exc:
    print("HTTP 状态码：", exc.status_code)
    print("响应：", exc.response)

是否应该重试

错误	自动重试	原因
`400`／`401`／`402`／`403`／`404`	否	需要修改请求、密钥、余额或权限。
`408`／部分 `429`	可有限重试	先等待并使用指数退避。
`500`／`502`／`503`／`504`	可有限重试	通常属于临时性服务器或上游故障。
流式中途断开	谨慎	重新请求可能生成不同内容或造成前端重复。

HTTP 状态码Copy Anchor Link

错误对象示例Copy Anchor Link

Python 异常处理Copy Anchor Link

是否应该重试Copy Anchor Link

On this page

HTTP 状态码

错误对象示例

Python 异常处理

是否应该重试