Skip to main content
OpenAI client retries turn on the OpenAI SDK’s built-in retry engine so transient 429s and network blips on the native client path are retried automatically.
The same “native OpenAI client path” referenced here is where the Responses API routing lives — see OpenAI → Transparent Responses API routing.

​
Quick Start

1

Turn it on with one env var (zero code change)

The user runs an agent; transient rate limits and network blips retry automatically on the native OpenAI client path.
2

Pass max_retries through the client factory

3

Construct the client directly

​
How It Works

The value is forwarded into the underlying openai SDK, which honours Retry-After on 429s and applies exponential backoff for transient errors.
OPENAI_MAX_RETRIES is orthogonal to the sync→async loop handling. Since PraisonAI PR #5682, the cached AsyncOpenAI is rebuilt whenever the running loop changes — so sync callers bridging into the async path via per-call asyncio.run no longer see Event loop is closed on reuse, independent of the retry budget. See OpenAI → Fallback is quieter now.
praisonai --auto uses LiteLLM first and only falls back to OpenAI on error. OPENAI_MAX_RETRIES therefore only takes effect on that fallback path — see Auto Mode Providers for the fallback flow. The LiteLLM leg has its own separate retry policy (2 retries, 1s → 2s backoff).

​
Configuration Options

Precedence: explicit arg > OPENAI_MAX_RETRIES env var > SDK default.
Non-integer OPENAI_MAX_RETRIES (e.g. "abc") is silently ignored and the SDK default takes over — no crash.

​
Which Approach to Use

Match the retry surface to how broadly you want the policy to apply.

​
Common Patterns

Turn it on globally with one env var — for production deployments where every call should retry the same way.
Scope it to one call site — pass max_retries explicitly when you build the client for a hot path.
AutoAgents also accepts a max_retries argument, but that controls its own config-generation retries — it is separate from the SDK-level max_retries documented here. Use OPENAI_MAX_RETRIES for a process-wide native-client policy.
Local server (LM Studio / vLLM) — leave it off — local endpoints rarely emit Retry-After, so retries are wasted latency.

​
Best Practices

One place, no code change, easy to bump per environment. Set OPENAI_MAX_RETRIES once and every native call inherits it.
This matches the SDK’s typical rate-limit budget without inflating tail latency.
As of the fix for #3135, a default Agent() retries transient errors (RetryBackoffConfig(), up to 3 retries) even without retry=True. If you also set OPENAI_MAX_RETRIES=5, both layers fire — 5 × 3 = 15 attempts on a rate limit. Pass Agent(..., retry=False) to disable the agent-loop layer if you only want the SDK-level policy.
Retries help transient blips; for provider outages use LLMConfig(fallbacks=[...]) — see Model Fallback.
Stop interrupts backoff sleeps within ~200 ms. See Cancel during LLM retry backoff.

Agent Retry

Retry the LiteLLM-backed agent loop with jittered exponential backoff.

Model Fallback

Fail over to alternate models during provider outages.

LLM Error Classification

Understand which errors are retryable versus fatal.