API 错误排障 — 429/401/invalid model/余额不足完整处理指南

AI API 常见错误排查：429 请求过于频繁怎么处理、401 Unauthorized 原因清单、invalid model 报错、余额不足（insufficient quota）怎么充值，含 curl/SDK 重试代码示例。

调 AI API 遇到报错？本页按错误码逐个给出排查路径。

429 — 请求过于频繁 / Rate Limit

含义：短时间内请求过多，触发限流。

排查顺序：

先看是不是自己代码的问题（循环里忘了 sleep？并发数设太高？）
检查是否多个进程共用一个 Key（叠加触发限额）
确认重试逻辑：429 应该退避重试（指数退避），不是立刻重发

正确处理代码：

import time

for attempt in range(5):
    resp = client.chat.completions.create(...)
    if resp.status_code != 429:
        break
    wait = 2 ** attempt  # 1s, 2s, 4s, 8s, 16s
    time.sleep(wait)

预防：

批量任务加并发控制（如信号量限 5 并发）
OpenAI SDK 自带重试：OpenAI(api_key=..., max_retries=5)

401 — Unauthorized

含义：API Key 无效。

按序检查：

Key 前缀：必须是 sk- 开头
多余字符：复制时带进了空格/换行（echo -n $KEY | wc -c 验证长度）
Key 状态：控制台看是否被删/禁用
环境变量：echo $OPENAI_API_KEY（或对应变量名）确认注入了
多个 Key 混用：确认代码里读的变量和你充值的是同一个账号

特别注意（Claude Code 用户）：Claude Code 会同时发 Authorization: Bearer 和内部 x-api-key 头。没猫饼网关已兼容此行为，但如果用其他中转遇到 401，检查中转是否处理了双认证头。

invalid model / model not found

含义：model 字段的值不在可用列表里。

常见原因：

拼写错误：gpt-5.6-terra ✅ / gpt5.6terra ❌
用了不存在的版本号（如 gpt-5.7——还没发布）
该模型在你使用的分组里未启用

解决：

# 列出全部可用模型
curl https://api.meimaobing.ai/v1/models \
  -H "Authorization: Bearer sk-你的Key"

对照模型目录确认精确的 model 名。

余额不足 — insufficient quota

含义：API 钱包额度不够本次调用。

注意：对话/工作台/画布用的是应用钱包（订阅/预付），API 调用的是 API 钱包——两本独立，详见钱包规则。

解决：

去商店充值 API 额度（¥1 = $1 = 500,000 quota）
支付后秒级到账；如果购买记录页显示“入账处理中”，等几秒刷新
控制台确认余额已更新

预防：在控制台设置余额告警，余量低于阈值时收到通知。

5xx — 服务器错误

含义：上游渠道临时故障。

处理：

重试（退避 5-30 秒）
换模型试试（同一能力档有多个可选，见模型目录）
持续失败超过 10 分钟 → 联系客服（Telegram @meimbaibot），附上错误信息和时间

连接超时 / 网络错误

排查：

# 测连通性
curl -w "\nconnect: %{time_connect}s\ntotal: %{time_total}s\n" \
  https://api.meimaobing.ai/v1/models \
  -H "Authorization: Bearer sk-test"

# 预期：connect < 1s，返回 401（Key 是假的但通了）

connect 超过 3s：本地网络问题（换网络/DNS）
能连但请求超时：长生成任务，SDK 的 timeout 调大（默认 30s 对长输出不够）

API 错误排障 — 429/401/invalid model/余额不足 完整处理指南