OpenAI API 错误处理与重试：401/429/5xx 实战模式

生产环境的 OpenAI API 调用不会一直顺利 - - 4 类错误必须准备。401/429/5xx/timeout，处理策略各不相同。

1. 错误分类总览

经验：401/400 不重试；429/5xx/timeout 重试。

2. 401：立刻失败，排查认证

401 的本质是"你的请求没通过认证"。常见根因：

• API key 过期或被撤销
• project 配额耗尽（hard limit）
• organization 权限被改

策略：立刻失败，把错误返回给调用方；触发内部报警；自动检查 key 健康度（如每日定时 ping /v1/models）。

3. 429：尊重 Retry-After + 指数退避

OpenAI 会在 429 响应里带 Retry-After header：

HTTP/1.1 429 Too Many Requests
retry-after: 0.5

先用这个值重试；如果 header 缺失，用指数退避（base 1s，max 60s）+ jitter（±20% 随机扰动）：

import random, time

def retry_after_429(attempt, base=1.0, cap=60.0, jitter=0.2):
    delay = min(cap, base * (2 ** attempt))
    delay *= 1 + random.uniform(-jitter, jitter)
    return max(0.1, delay)

实战中常见的坑：忽视 Retry-After 直接短间隔重试，导致 429 持续；多个进程同时打 API 同时触发限速（雷击）。

4. 5xx：3-5 次重试 + request-id + 降级

5xx 是 OpenAI 上游服务异常。策略：

def call_api_with_5xx_retry(client, request, max_retries=5):
    for attempt in range(max_retries):
        try:
            return client.responses.create(**request)
        except APIStatusError as e:
            if e.status_code < 500:
                raise  # 4xx 不重试
            request_id = e.request_id  #  必记日志
            log.warning("5xx from OpenAI", extra={"request_id": request_id, "attempt": attempt})
            if attempt == max_retries - 1:
                # 最后一次还失败，降级到备用模型
                return degraded_response()
            time.sleep(retry_after_429(attempt, cap=30))
        except APITimeoutError:
            time.sleep(retry_after_429(attempt, base=2, cap=10))
    raise RetryExhausted()

关键细节：

• request-id 必须记日志 - - OpenAI 工单排查需要这个 ID（响应 header x-request-id）
• 重试用完后降级 - - 切到备用模型（GPT-5.6 Luna） 或返回降级响应（"服务暂时不可用，请稍后"）
• 不要让 5xx 阻塞用户 - - 前端要显示"正在处理"或排队状态

5. Streaming 错误：回滚到 last_successful_token

Streaming（SSE）模式的错误处理要复杂：

• 错误不是一次性返回，而是嵌入在 event stream 里（type=error）
• 不要整个对话重发 - - token 消耗翻倍
• 维护 last_successful_index，错误时从该位置继续

async for event in stream:
    if event.type == "response.output_text.delta":
        output_text += event.delta
        last_successful_index = len(output_text)
    elif event.type == "error":
        # 从 last_successful_index 重发请求（保留已生成内容）
        await resume_from(last_successful_index)

附加保护：

• 设 stream-level timeout（建议 60s），超时即放弃
• 客户端缓存已接收 token，避免因网络断流丢失
• 关键事件用 event-id 去重（防止客户端重连收到重复事件）

6. 错误预算（Error Budget）

不要无限重试。设两个阈值：

熔断后逐步放行（half-open 状态）：少量请求试探，恢复后全开。

# 用滑动窗口算错误率（伪代码）
def is_circuit_open(window_minutes=5):
    recent_errors = redis.get(f"errors:{window_minutes}m") or 0
    recent_total = redis.get(f"total:{window_minutes}m") or 1
    error_rate = recent_errors / recent_total
    return error_rate > 0.05  # 5%

7. 实战代码模板

from openai import OpenAI, APIStatusError, APITimeoutError, RateLimitError
import backoff
import logging

log = logging.getLogger(__name__)

class ResilientOpenAIClient:
    def __init__(self, api_key, fallback_model="gpt-5.6-luna"):
        self.client = OpenAI(api_key=api_key)
        self.fallback_model = fallback_model
    
    @backoff.on_exception(
        backoff.expo,
        (APIStatusError, APITimeoutError),
        max_tries=4,
        giveup=lambda e: isinstance(e, APIStatusError) and 400 <= e.status_code < 500,
    )
    def chat(self, **kwargs):
        try:
            return self.client.responses.create(**kwargs)
        except RateLimitError as e:
            retry_after = float(e.headers.get("retry-after", "1"))
            log.warning("429 from OpenAI", extra={"retry_after": retry_after, "request_id": e.request_id})
            time.sleep(retry_after)
            raise  # backoff 触发重试
        except APIStatusError as e:
            if e.status_code >= 500:
                log.error("5xx from OpenAI", extra={"request_id": e.request_id, "status": e.status_code})
            raise
    
    def chat_with_fallback(self, **kwargs):
        try:
            return self.chat(**kwargs)
        except Exception as e:
            log.exception("Primary API failed, switching to fallback", extra={"error": str(e)})
            kwargs["model"] = self.fallback_model
            return self.client.responses.create(**kwargs)

8. 常见错误与排查

• 401 持续出现 → key 过期；去 platform.openai.com 检查 + 轮换 key
• 429 持续 → 流量超限；升级 tier 或加 organization-wide rate limit
• 5xx 高峰 → OpenAI 服务异常；订阅 status.openai.com RSS；触发熔断 + 切备用
• Streaming 中途断流 → 客户端没缓存已接收 token；增加 last_successful_index 持久化
• 错误预算反复熔断 → 备用模型也不够；准备第二 provider（Azure OpenAI 兜底）

9. 下一步

• 《OpenAI API 入门：第一个 GPT-5.6 调用详解》
• 《GPT-5.6 选型指南：Sol / Terra / Luna 怎么选》
• 《GPTMap 文章维护指南：半年重测、版本同步与下架》 - - 当错误率变化时该触发重测

更新记录

• 2026-08-08：首次发布