Implementation:Openai Openai python API Error Hierarchy

Knowledge Sources	openai-python OpenAI Error Codes
Domains	Error_Handling, SDK_Infrastructure
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete exception hierarchy for handling OpenAI API errors provided by the OpenAI Python SDK.

Description

The exception module defines a typed hierarchy of exceptions mapping HTTP status codes to Python exception classes. APIStatusError subclasses carry the HTTP response, status code, and parsed error body. APIConnectionError and APITimeoutError handle network-level failures. The base APIError class provides common attributes like message, body, and request_id.

Usage

Import and catch specific exception types for granular error handling in production code. Use broad except openai.APIError for general error catching.

Code Reference

Source Location

Repository: openai-python
File: src/openai/_exceptions.py
Lines: L31-161

Signature

class OpenAIError(Exception):
    """Base exception for all OpenAI errors."""

class APIError(OpenAIError):
    message: str
    request: httpx.Request
    body: object | None
    code: str | None
    param: str | None
    type: str | None

class APIConnectionError(APIError):
    """Raised on network connection failures."""

class APITimeoutError(APIConnectionError):
    """Raised when a request times out."""

class APIStatusError(APIError):
    response: httpx.Response
    status_code: int
    request_id: str | None

class BadRequestError(APIStatusError):       # 400
    status_code: Literal[400] = 400

class AuthenticationError(APIStatusError):    # 401
    status_code: Literal[401] = 401

class PermissionDeniedError(APIStatusError):  # 403
    status_code: Literal[403] = 403

class NotFoundError(APIStatusError):          # 404
    status_code: Literal[404] = 404

class ConflictError(APIStatusError):          # 409
    status_code: Literal[409] = 409

class UnprocessableEntityError(APIStatusError):  # 422
    status_code: Literal[422] = 422

class RateLimitError(APIStatusError):         # 429
    status_code: Literal[429] = 429

class InternalServerError(APIStatusError):    # >=500
    status_code: int

class LengthFinishReasonError(OpenAIError):
    """Raised when response was truncated due to max_tokens."""

class ContentFilterFinishReasonError(OpenAIError):
    """Raised when content was filtered."""

Import

import openai
from openai import (
    APIError,
    APIConnectionError,
    APITimeoutError,
    APIStatusError,
    BadRequestError,
    AuthenticationError,
    PermissionDeniedError,
    NotFoundError,
    RateLimitError,
    InternalServerError,
)

I/O Contract

Inputs

Name	Type	Required	Description
HTTP response	httpx.Response	Yes (APIStatusError)	The error HTTP response
Connection failure	Exception	Yes (APIConnectionError)	The underlying connection error

Outputs

Name	Type	Description
message	str	Human-readable error message
status_code	int	HTTP status code (APIStatusError only)
body	object or None	Parsed error response body
request_id	str or None	OpenAI request ID from response headers
code	str or None	Error code from response body

Usage Examples

Granular Error Handling

import openai
from openai import OpenAI

client = OpenAI()

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello"}],
    )
except openai.RateLimitError as e:
    print(f"Rate limited. Retry after backoff. Request ID: {e.request_id}")
except openai.AuthenticationError as e:
    print(f"Invalid API key: {e.message}")
except openai.BadRequestError as e:
    print(f"Bad request: {e.body}")
except openai.APIConnectionError:
    print("Network error - check connectivity")
except openai.APITimeoutError:
    print("Request timed out")
except openai.APIStatusError as e:
    print(f"API error {e.status_code}: {e.message}")

Automatic Retries

# The client retries transient errors automatically
client = OpenAI(max_retries=5)  # Retry up to 5 times with backoff

# Or disable retries for specific calls
response = client.with_options(max_retries=0).chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment