问题排查9 分钟阅读发布于：2026-03-31更新于：2026-08-07

OpenAI 401 与 429 报错排查清单

基于 OpenAI 官方文档，快速定位 Unauthorized 与限流/额度类报错，并给出可落地处理步骤。

作者 Heizi· 创始人 & 编辑· 发布于: 2026-03-31· 更新于: 2026-08-07实测验证

1）401：先区分认证问题还是策略问题

OpenAI 错误文档中，401 不止一种原因，包括认证失败与 IP 白名单不匹配等。不要把 401 当成单一问题。如果从头开始，正确获取 OpenAI API Key 可以避免大部分 401 问题。

建议先确认：当前使用的是哪把 Key、归属哪个项目、请求出口 IP 是否符合项目策略。关于正确配置密钥，包括权限范围和项目分配，请参阅我们的设置指南。

核对 Authorization 头格式
确认 Key 归属组织/项目是否正确
检查 IP 白名单配置

2）429：区分速率限制与额度不足

OpenAI 常见的 429 包括“请求频率过快”和“额度/预算已用尽”，两者处理路径不同。

前者要做流量平滑与重试，后者要优先检查计费、limits 和项目预算。了解你的额度和消费限制有助于区分计费问题和流量突发。

3）按 RPM/RPD/TPM/TPD/IPM 理解限额

OpenAI 限额是多维度的，可能先撞到 RPM，即使 TPM 还没满，因此要同时看请求和 token 两个维度。完整的 OpenAI API 参考指南记录了每个等级和模型的限额。

官方文档也强调：失败请求同样计入限额，盲目立刻重试会让问题更严重。

4）实现安全重试策略

对可重试错误使用带抖动的指数退避，并结合去重与超时预算，防止形成重试风暴。

同时把 max_tokens 调整到接近真实输出规模，因为限流计算会参考 max_tokens 的估算影响。

5）建立可执行的生产 Runbook

如果 401/429 问题反复出现，建议沉淀 Runbook：责任人、告警阈值、回滚方案、对外沟通模板。

在高峰期，标准化的短流程比临时排查更能保证恢复速度。

真实调试案例：一个不是速率限制的 429

我们曾花了两小时追查一个持续的 429 错误，结果发现原因完全不同。事情是这样的：

我们的应用在一次部署后每个请求都返回 429。我们以为是速率限制，实施了激进退避 —— 但即使零流量 10 分钟后错误仍在继续。这就是线索：真正的速率限制在 60 秒内会重置。

实际原因：我们的新部署有一个 bug，一个容器里的 API Key 环境变量为空。OpenAI 返回了 429（而非 401），因为空 Key 触发了不同的内部路径。修复只需改一行配置。

教训：如果 429 在零流量超过 60 秒后仍然存在，那就不是速率限制。检查你的 Key、请求头和部署配置。

我们生产环境使用的重试代码模式

这是我们经过数月生产使用后打磨出的重试模式。包含带抖动的指数退避和最大重试限制：

python

import time
import random
from openai import OpenAI

client = OpenAI()

def call_with_retry(model, messages, max_retries=5):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model=model,
                messages=messages
            )
            return response
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            # Exponential backoff with jitter: 1s, 2s, 4s, 8s + random
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"Attempt {attempt+1} failed, waiting {wait:.1f}s...")
            time.sleep(wait)

生产实测 —— 可处理 429 和临时网络错误