开发文档

错误处理与重试

请求出错时返回对应的 HTTP 状态码，响应体沿用所用协议的错误格式。按状态码区分「改请求」和「可重试」两类错误，是稳定接入的关键。

错误格式

OpenAI 兼容协议：

json

{
  "error": {
    "message": "用户额度不足, 剩余额度: $0.01",
    "type": "new_api_error",
    "code": "insufficient_user_quota"
  }
}

Anthropic 原生协议：

json

{
  "type": "error",
  "error": { "type": "invalid_request_error", "message": "..." }
}

状态码速查

状态码	含义	处理方式	可重试
`400`	请求参数错误：缺少字段、格式不符合协议、模型不支持该参数	按 `error.message` 修正请求	否
`401`	API Key 缺失、无效、已删除或过期	检查请求头和 Key 状态，见认证	否
`403`	余额或 Key 额度不足，或该 Key 无权使用此模型	充值，或调整 Key 的额度与模型限制	否
`404`	路径不存在，多为 Base URL 写错	OpenAI SDK 带 `/v1`，Anthropic / Gemini SDK 不带	否
`429`	请求过于频繁	降低并发，按指数退避重试	是
`500` / `502`	服务暂时异常	稍后重试	是
`503`	该模型暂时没有可用资源，或模型 ID 不存在	核对模型 ID；确认无误则稍后重试	是
`504`	处理超时	重试；生图任务可按任务 ID 取回结果	是

重试策略

只对 429、5xx 和网络错误重试，4xx（除 429）重试也不会成功。推荐指数退避加随机抖动：

retry.py

import random, time
from openai import OpenAI, APIConnectionError, APIStatusError, RateLimitError

client = OpenAI(api_key="sk-...", base_url="https://api.flyrouter.ai/v1", max_retries=0)

def chat(messages, attempts=5):
    for i in range(attempts):
        try:
            return client.chat.completions.create(model="gpt-6.1-sol", messages=messages)
        except (RateLimitError, APIConnectionError) as e:
            err = e
        except APIStatusError as e:
            if e.status_code < 500:
                raise  # 参数、鉴权、余额问题，重试无用
            err = e
        time.sleep(min(2 ** i, 30) + random.random())
    raise err

官方 OpenAI / Anthropic SDK 默认会自动重试 2 次（针对 429 与 5xx），一般场景直接调大 max_retries 即可，不必自己实现。

超时设置

大模型首字可能需要几秒到几十秒，深度思考时更久。客户端读超时建议至少 10 分钟，或使用流式输出。
图像生成同样建议 10 分钟以上的超时。

计费与失败请求

请求开始时按预估用量预扣额度，完成后按实际用量多退少补。
返回错误、没有产生内容的请求会退还预扣额度，不扣费。
流式请求中途断开时，已生成的部分照常计费。

联系支持

问题持续出现时，请联系我们，并附上请求时间、模型 ID 和完整的错误信息（不要附带 API Key）。

错误处理与重试

错误格式#

状态码速查#

重试策略#

超时设置#