错误处理

错误码字典

HTTP 状态码	典型信息	含义	可重试	处理方式
400	无效的请求 / 参数错误	请求体格式或参数不对	❌	修正参数，检查模型是否支持该参数
401	无效的令牌	密钥错误、已删除或禁用	❌	检查密钥
403	无权访问 xxx 分组 / IP 不在允许列表	分组或 IP 限制	❌	换分组 / 修改 IP 白名单
403	用户额度不足 / 预扣费额度失败	余额不足	❌	充值
404	Not Found	路径错误（多半是 /v1 问题）	❌	见 Base URL 与兼容性
429	当前分组负载已饱和 / 请求过于频繁	限流或并发已满	✅	指数退避重试，或换分组
503	分组 xxx 下模型 xxx 无可用渠道	分组不支持该模型，或渠道暂时全部不可用	⚠️	先确认模型在该分组内；确认无误再稍后重试或换分组
500 / 502	上游错误	上游临时故障	✅	退避重试；持续出现请换分组
524 / 连接重置	—	非流式请求超时	⚠️	改用流式，见 流式输出与超时

错误响应示例（OpenAI 格式）：

{
  "error": {
    "message": "分组 claude-pro 下模型 claude-fable-5-2 无可用渠道（distributor）",
    "type": "..."
  }
}

重试策略

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

client = OpenAI(api_key="sk-xxxx", base_url="https://aimoniker.top/v1")

def chat_with_retry(messages, model="gpt-5.6", max_attempts=4):
    for attempt in range(max_attempts):
        try:
            return client.chat.completions.create(model=model, messages=messages)
        except APIStatusError as e:
            if e.status_code not in (429, 500, 502, 503):
                raise  # 4xx 参数/鉴权/余额问题，重试没有意义
        except APIConnectionError:
            pass
        time.sleep(min(2 ** attempt + random.random(), 30))  # 1s, 2s, 4s... 加随机抖动
    raise RuntimeError("重试多次仍失败")

流式输出中途断开时不要自动重试

流式请求已经开始输出后断开，上游通常已经产生了费用。自动重试会让同样的内容重复计费。应该把已收到的内容保留下来，由用户决定是否继续。

排查时提供什么

在 QQ 群反馈问题时，请提供：报错原文、请求时间、模型、分组，以及 使用日志 中对应记录的截图。不要发送完整密钥。