Troubleshooting9 min readPublished: 2026-03-31Updated: 2026-08-07

OpenAI 401 and 429 Errors: Practical Fix Checklist

Diagnose unauthorized and rate/quota errors quickly with a production-ready checklist based on official OpenAI guidance.

By Heizi· Founder & Editor· Published: 2026-03-31· Updated: 2026-08-07Hands-on tested

1) 401 errors: split auth vs policy causes

OpenAI error guidance lists multiple 401 scenarios, including invalid credentials and IP allowlist mismatch. Treat 401 as a category, not a single root cause. If you're starting from scratch, getting your OpenAI API key correctly from the start prevents most 401 issues.

Start by checking which key is used, which project it belongs to, and whether your request source IP matches project policy. For proper key configuration including permission scoping and project assignment, see our setup guide.

Validate Authorization header format
Confirm key belongs to the expected organization/project
Review IP allowlist settings

2) 429 errors: rate limit vs quota

OpenAI distinguishes at least two common 429 patterns: rate-limit reached and current quota exceeded. The mitigation path is different for each.

If requests are too fast, smooth traffic and retry with backoff. If quota is exceeded, check billing, limits, and project budget settings. Understanding your quota and spending limits helps you distinguish billing issues from traffic spikes.

3) Read limits using RPM/RPD/TPM/TPD/IPM

OpenAI rate limits are measured across several dimensions. You can hit RPM first even when TPM still looks healthy, so monitor both request and token dimensions. The full OpenAI API reference documents these limits for each tier and model.

Unsuccessful requests still count toward per-minute limits, so repeated immediate retries can worsen incidents.

4) Implement safe retries

Use exponential backoff with jitter for retriable failures. Pair retries with request deduplication and timeout budgets to prevent retry storms.

Also tune max_tokens close to expected output size, because rate-limit accounting can depend on max_tokens estimates.

5) Production runbook for recurring incidents

For recurring 401/429 incidents, create a runbook with ownership, alert thresholds, rollback paths, and communication templates.

A short, repeatable checklist is usually more valuable than ad-hoc debugging during peak traffic.

Real Debugging Session: A 429 That Wasn't Rate Limit

We once spent two hours chasing a persistent 429 error that turned out to be something entirely different. Here's what happened:

Our application started returning 429 on every request after a deployment. We assumed rate limiting and implemented aggressive backoff — but the errors continued even after 10 minutes of zero traffic. That was the clue: true rate limits reset within 60 seconds.

The actual cause: our new deployment had a bug where the API key environment variable was empty in one container. OpenAI returned 429 (not 401) because the empty key triggered a different internal path. The fix was a one-line config correction.

Lesson: if 429 persists beyond 60 seconds of zero traffic, it's not a rate limit. Check your key, your headers, and your deployment configuration.

Retry Code Pattern We Use in Production

Here's the retry pattern we've refined over months of production usage. It includes exponential backoff with jitter and max-retry limits:

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)

Tested in production — handles both 429 and transient network errors