OpenAI 兼容 API 429 限流排错

第一步应该查什么？

调整并发前，先读 JSON 中的错误代码和消息。429 是一类状态，不是单一结论。OpenAI 当前错误指南将请求速率限制、预付额度耗尽和组织消费上限都列为 429。

保存一份完整且脱敏的失败证据

curl -sS -D /tmp/headers.txt -o /tmp/body.json \
  https://monkeytheme.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID_FROM_YOUR_LIST","messages":[{"role":"user","content":"Reply with OK"}],"max_completion_tokens":16}'

sed -n '1,20p' /tmp/headers.txt
python3 -m json.tool /tmp/body.json

保留状态码、Retry-After、请求 ID、时间、接口和脱敏后的错误体。工单或截图中不要出现 Bearer Token。

重试时避免形成请求风暴

# Python SDK：排错时明确指定重试次数
import os
from openai import OpenAI
client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url="https://monkeytheme.com/v1",
    max_retries=2,
)

# Node.js SDK
const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://monkeytheme.com/v1",
  maxRetries: 2,
});

OpenAI 官方 Python 和 Node.js SDK 当前默认会对符合条件的 429 重试两次。如果队列、Worker、HTTP 库和 SDK 都在重试，一次用户操作会产生多次上游请求。应指定一个重试责任层，限制次数；有 Retry-After 时按其等待，没有时再使用带随机抖动的指数退避。

按这个顺序排查

1. 确认域名和接口。本文使用 https://monkeytheme.com/v1。
2. 用同一个 Key 请求 /v1/models，复制准确的 Model ID。
3. 保存 429 的响应头和 JSON，注意隐藏 Key。
4. 区分请求/Token 速率、余额不足和消费上限。
5. 合并计算 SDK、代理、队列和应用层的重试。
6. 增加重试次数前，先降低并发。
7. 问题持续时，向支持人员提供时间、请求 ID、模型、接口和脱敏错误代码。

本文没有作出的承诺

模型列表成功不代表生成容量一定可用。429 也不能直接证明模型服务商宕机；响应没有 Retry-After 时，立即重试同样不安全。不同网关和上游的限制名称与范围可能不同，应以真实响应体为准。

官方资料与相关教程

• OpenAI API 错误代码：当前 429 分类与重试建议。
• RFC 6585 第 4 节：HTTP 429 与可选的 Retry-After。
• openai-python 重试说明和 openai-node 重试说明。
• API Key 与模型排错
• API 504 超时排错

常见问题