适用场景

  • Solopreneur,GPT-5.5 跑在生产 SaaS 后端
  • 月营收 500 美金以上,挂了用户会投诉
  • 想做规范的重试 + 降级 + 告警

429 rate_limit_exceeded

症状

  • HTTP 429
  • Body 里 error.type = rate_limit_exceeded
  • Response header 里 retry-after 字段(秒数)

根因排查

OpenAI 限流分 RPM(每分钟请求数)与 TPM(每分钟 token 数)。看 response header:

  • x-ratelimit-limit-requests / x-ratelimit-remaining-requests
  • x-ratelimit-limit-tokens / x-ratelimit-remaining-tokens

哪个 remaining 接近 0,就是哪一条触发。

修复

短期:

  • 按 retry-after 等待后重试(指数退避)
  • 降低并发(从 10 降到 5)

长期:

  • OpenAI tier 升级(充值或长期使用自动升)
  • 多 key 轮转(多账号或多中转 key)
  • 异步任务走 batch API,与实时流量分流

timeout

症状

  • 客户端 raise TimeoutError 或 SDK 抛 APITimeoutError
  • 一般 30-60 秒触发(SDK 默认)

根因排查

第一步:curl 测端点连接性:

curl -v https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -d '{"model":"gpt-5.5","max_tokens":100,"messages":[{"role":"user","content":"hi"}]}'
  • 1 秒内连上 + 慢响应:模型层慢
  • 几秒内连不上:网络层有问题

第二步:看请求量:

  • 单请求 max_tokens 是否过大(>4000)
  • streaming 是否开了(没开容易长 wait)

修复

  • 开启 streaming,降低首字延迟
  • 拆短 max_tokens(按业务实际需要)
  • 网络层问题切中转(国内常见)
  • SDK 把 timeout 调高(60-120 秒),给模型留时间

insufficient_quota / billing

症状

  • HTTP 401 或 429
  • Body 里 error.type = insufficient_quota
  • 或 error.code = billing_hard_limit_reached

根因排查

  • OpenAI 后台 → Settings → Billing,看额度是否耗尽
  • 卡是否被风控(刷流水异常 / 国家 mismatch)
  • 月预算上限触顶

修复

  • 充值或开通自动续费
  • 卡被风控:换一张卡或办海外银行卡(Mercury / Wise / 实体海外卡)
  • 月预算上限调整

预防

强烈建议三层预警:

  • OpenAI 后台 usage 告警(月 50% / 80%)
  • 业务侧自己埋点累计 token,80% 发邮件
  • 中转方后台单 key 月限额告警

context_length_exceeded

症状

  • HTTP 400
  • Body 里 error.code = context_length_exceeded

根因

输入 token + max_tokens > 模型上下文窗口。常见踩坑:

  • RAG 检索后塞太多 chunk
  • 历史对话累计太长没截断
  • 文档对话 SaaS 一次塞完整 PDF

修复

  • 请求前用 tiktoken 算 token,超过窗口 90% 就裁剪
  • 对话历史用 summarize 而不是 full history
  • RAG chunk 数量按 token 总量动态调整

model_not_found

症状

  • HTTP 404 或 400
  • error.message: The model ‘xxx’ does not exist or you do not have access

根因

  • 模型名写错(gpt-5.5 vs gpt-5-5 中转方命名差异)
  • 账号没开通该模型权限(新模型有时需要 tier 达到才能用)
  • 走中转时,中转方未开通该模型

修复

  • 维护一份模型名映射表(provider → model name)
  • 中转方后台启用该模型
  • 主路失败回退到备路(GPT-5-mini)

invalid_request_error

症状

  • HTTP 400
  • error.type = invalid_request_error

常见原因

  • max_tokens 超过模型最大值
  • messages 格式错(空 content 或角色错)
  • tool_use 协议字段不全
  • temperature / top_p 超出 0-2 范围

修复

  • SDK 升到最新版,字段对齐
  • 在请求构造前加 validator
  • log 完整请求 body 帮助 reproducer

重试与降级策略

三层结构

层触发动作
第 1 层timeout / 429 / 5xx同 provider 同模型重试 1-2 次,指数退避(2s / 4s)
第 2 层第 1 层全失败模型降级(GPT-5.5 → GPT-5-mini)
第 3 层第 2 层失败provider 切换(官方 ↔ 中转)

实现要点

# 伪代码
def call_with_fallback(prompt):
    for attempt in range(2):
        try:
            return call_provider("official", "gpt-5.5", prompt)
        except (TimeoutError, RateLimitError) as e:
            sleep(2 ** attempt)
    
    try:
        return call_provider("official", "gpt-5-mini", prompt)
    except Exception:
        pass
    
    return call_provider("relay-A", "gpt-5.5", prompt)

Circuit breaker

防止下游连续失败导致雪崩,加 circuit breaker:

  • 1 分钟内 official + gpt-5.5 失败率 > 50%
  • 自动切到 relay-A 主路
  • 10 分钟后探测一次 official,恢复正常再切回

监控与告警

必须埋点的指标

  • 请求成功率(按 provider × model 拆)
  • P50 / P95 / P99 延迟
  • 各类错误码计数
  • 月累计 token / 月预算占比

告警阈值参考

  • 错误率 > 5% 持续 5 分钟
  • P95 延迟 > 5 秒持续 5 分钟
  • 月预算占比 > 80%
  • 单用户日 token > P99 × 3(滥用嫌疑)

紧急处理流程

立刻动作：

  • 检查 OpenAI status page(status.openai.com)
  • 切到备路 provider
  • 临时降级到 GPT-5-mini

短期动作(1 小时内)

  • 检查后端日志,定位是单点(某个用户 / 某段 prompt)还是全局
  • 联系 OpenAI 客服(如果是账号问题)
  • 通知用户(“AI 服务降级运行中”)

长期动作(1 天内)

如果发现是 provider 单点问题反复发生,考虑长期备路。Solopreneur 早期可以接入一条独立开发者用得起的 Claude 4.7 / GPT-5.5 中转作为备路,官方主路挂掉时自动切换,SaaS 不下线。

升级路径

  • 早期 Solopreneur 阶段:1 个 provider + 简单重试
  • 月营收 500 美金以上:1 主 1 备(官方 + 中转或两家中转)
  • 月营收 2000 美金以上:1 主 2 备(官方 + 中转 A + 中转 B)
  • 月营收 5000 美金以上:自托管 OneAPI / litellm + 多账号轮转

相关阅读