配置排错
报错排查手册:从状态码到修复动作
排错的原则是控制变量:先用最短的命令确认通路,再回到工具里改配置。大多数报错都落在五个状态码里,每个状态码对应的第一检查项是固定的,不需要碰运气。
先跑两条诊断命令
任何工具里报错,都先脱离工具、用 curl 直接打接口。两条命令都通,说明问题在工具配置;命令就不通,说明问题在 Key、地址或网络。
# 1)鉴权与模型列表(通 = Key 和域名都对)
curl -s https://codebridgeapi.top/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"
# 2)最小对话请求(通 = 模型名和协议都对)
curl -s https://codebridgeapi.top/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"<从 /v1/models 复制>","messages":[{"role":"user","content":"ping"}]}'五个状态码,五个第一反应
| 状态码 | 含义 | 第一检查项 | 典型修复 |
|---|---|---|---|
| 401 | 鉴权失败 | Authorization 头里的 Key 是否完整、无空格、属于本站 | 重新从控制台复制 Key;确认没把别的平台的 Key 填进来 |
| 403 | 无权访问该资源 | Key 是否被禁用/回收,或该模型分组是否对你的账号开放 | 控制台确认 Key 状态与可用分组;必要时新建 Key |
| 404 | 路径不存在 | Base URL 与协议是否成对(OpenAI 兼容带 /v1,Anthropic 兼容不带) | 改 Base URL,不要在末尾多拼一层路径 |
| 429 | 触发限流 | 是否短时间高并发,或多个任务共用同一把 Key | 退避重试;把批量任务的并发降下来或分 Key |
| 529 | 上游过载 | 是暂时性的,不是你的配置问题 | 指数退避重试;高峰期把重试间隔放宽 |
超时(无状态码)单独说:先区分"连接超时"和"读超时"。连接超时查网络与域名;读超时多见于长输出任务,把客户端超时上限调到 120 秒以上,或改用流式输出边收边处理。
一段可以抄走的重试退避
429 和 529 都适合自动重试,但要退避加抖动,不要固定间隔硬打。下面是 Python 版最小实现,Node 同理。
import time, random
from openai import OpenAI, APIStatusError
client = OpenAI(base_url="https://codebridgeapi.top/v1", api_key="YOUR_API_KEY")
def chat_with_retry(messages, model, max_retries=4):
for attempt in range(max_retries + 1):
try:
return client.chat.completions.create(model=model, messages=messages)
except APIStatusError as err:
# 只对暂时性状态码重试;4xx 配置类错误重试没有意义
if err.status_code not in (429, 500, 529) or attempt == max_retries:
raise
wait = min(2 ** attempt + random.random(), 30)
time.sleep(wait)401/403/404 属于配置错误,重试一万次也不会变好——修配置,别重试。