API requests sometimes run into trouble because of network drops, rate limits, server issues, or invalid parameters. Developers using the OpenAI Python SDK need to know which errors the SDK retries on its own and which ones require manual fixes to keep applications stable.
How the SDK Handles Errors and Retries
The OpenAI Python SDK automatically retries some errors using exponential backoff. If a request fails due to a temporary network or server problem, the SDK waits for a growing interval before trying again. It retries connection errors, HTTP 408 (timeout), 409 (conflict), 429 (rate limit), and all 5xx server errors. The max_retries parameter, often set to 2 by default, controls how many times the SDK will retry, but this and the list of retryable errors can shift between SDK versions. Retry logic uses a set number of attempts and follows server Retry-After instructions for rate-limited requests. The SDK may treat 408, 429, 500, 502, 503, and 504 as retryable, but the exact list depends on the SDK version and request type. For up-to-date details, check the official OpenAI Python SDK documentation.
Some errors never get retried. If a request is malformed (HTTP 400), uses a bad or expired API key (401), lacks permission (403), points to a missing resource (404), or sends unprocessable data (422), the SDK stops and expects you to fix the problem before trying again. Retrying non-idempotent operations, like writes or purchases, can cause duplicate actions if the server processes the request but the client misses the response. To prevent this, use idempotency controls or operation IDs when retrying requests with uncertain outcomes.
Understanding the Exception Hierarchy
The SDK sorts errors into a clear exception structure. At the top sits openai.APIError. Connection issues, such as APIConnectionError and its subclass APITimeoutError, get retried automatically. Status errors, handled by APIStatusError and its subclasses, map to specific HTTP codes. Only some status errors—429 and 5xx—are retried. Others, like 400 or 401, need direct fixes in your code. The exception class structure and inheritance can change between SDK releases, so always check your installed library's docs or codebase for the latest.
Timeouts: Why They Matter
The SDK sets a default timeout per request, which can be as long as 10 minutes in some releases, but this varies and is configurable at both the client and request level. You can set a client-wide default or override it for a single request, letting you choose different limits for interactive queries, batch jobs, streaming, or background work. For instance, OpenAI-maintained code sometimes uses a 120-second network timeout for certain tasks. To override the client default for a specific call, pass a timeout parameter in seconds. Interactive apps often use a 30–60 second timeout, while background jobs may allow more. If a request times out and gets retried, the total wait can add up fast—timeout × (retries + 1). For more, see the OpenAI Python SDK repository.
Practical Error Handling Patterns
Good error handling means catching exceptions that retries can't fix and logging details for later debugging. Here is a practical pattern for handling responses:
import logging
import openai
log = logging.getLogger("assistant")
def answer(question: str) -> str:
try:
r = client.responses.create(model=MODEL, input=question, max_output_tokens=800)
except openai.RateLimitError:
return "We're busy right now. Please try again in a minute."
except openai.APITimeoutError:
return "That took too long. Try a shorter question."
except openai.APIConnectionError:
log.exception("network problem reaching OpenAI")
return "Temporary connection problem."
except openai.BadRequestError as e:
log.error("bad request %s: %s", e.request_id, e.message)
return "Sorry, something went wrong."
except (openai.AuthenticationError, openai.PermissionDeniedError):
log.critical("OpenAI credentials rejected")
raise
if r.status == "incomplete":
log.warning("incomplete response %s: %s", r.id, r.incomplete_details)
return r.output_text
Keep in mind that APITimeoutError is a subclass of APIConnectionError, so catch it first. Always log the request_id for failed requests to help trace issues later.
Best Practices for Reliable API Calls
- Let the SDK handle retries for connection errors and retryable status codes. Retry logic in OpenAI-maintained code uses a set attempt budget and server-directed delays, with exponential backoff and caps to avoid endless waits.
- Set timeouts that fit your application's needs—shorter for interactive use, longer for background jobs. Timeout values can be global or per request, and should match your app's requirements.
- Fix non-retryable errors in your request or configuration, not by retrying. For operations with possible side effects, use idempotency controls or unique operation IDs to avoid duplicates if a retry happens after a partial failure.
- Log the request_id and check for incomplete responses to help with debugging.
For more on Python error handling, including how type mismatches can cause subtle bugs, see this earlier breakdown.
This guide is part of a broader series on the OpenAI Python SDK, with topics like streaming, structured outputs, function calling, evaluation, and cost management. For the full set of tutorials, visit recallrun.dev/guides/openai-sdk.
