Error Handling

~22 min · errors, retries, exceptions

Level 0Tokenizer

0 XP0/54 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

The SDK provides a rich exception hierarchy. Catching specific error types lets you handle each failure mode appropriately.

Error Hierarchy

The SDK auto-retries on APIConnectionError, 408, 409, 429, and 500+ with exponential backoff. Default is 2 retries. Customize with max_retries.

Retry only what time will fix

The retryable errors are the ones that will succeed on a second attempt: RateLimitError (429 — wait and try again), APIConnectionError (network blip), and 5xx server errors (transient backend issue). Everything else — 400 bad request, 401 auth, 404 not found, 422 validation — will fail identically on retry, so retrying just hammers the wall.

Production code wraps the call in tenacity.@retry (or equivalent) with an exception filter, exponential jitter, and a finite cap. Without the cap, a multi-day rate-limit incident becomes a multi-day spend incident.

Code

Catching APIStatusError vs APIError·python

import openai
from openai import OpenAI

client = OpenAI()

try:
    response = client.responses.create(
        model="gpt-5.4", input="Hello!",
    )
except openai.AuthenticationError as e:
    print(f"Auth error: {e}")         # 401
except openai.PermissionDeniedError:
    print("Permission denied")        # 403
except openai.NotFoundError:
    print("Model not found")          # 404
except openai.BadRequestError as e:
    print(f"Bad request: {e.message}") # 400
except openai.RateLimitError as e:
    retry = e.response.headers.get("retry-after")
    print(f"Rate limited, retry after: {retry}")  # 429
except openai.InternalServerError:
    print("Server error")             # 500+
except openai.APIConnectionError as e:
    print(f"Connection error: {e.__cause__}")
except openai.APITimeoutError:
    print("Request timed out")

Retry policy with tenacity·text

openai.APIError
├── openai.APIConnectionError
│   └── openai.APITimeoutError
├── openai.APIStatusError
│   ├── openai.BadRequestError           (400)
│   ├── openai.AuthenticationError       (401)
│   ├── openai.PermissionDeniedError     (403)
│   ├── openai.NotFoundError             (404)
│   ├── openai.RateLimitError            (429)
│   └── openai.InternalServerError       (500+)

External links

Exercise

Write retry_chat(messages) that retries on RateLimitError, APIConnectionError, and 5xx — exponential jitter, max 5 attempts. Manually trigger a 429 by spamming requests and verify the backoff actually waits.