CDX-301a · Module 2

Timeout Configs & Retry Policies

3 min read

Timeout and retry configurations determine how Codex handles slow API responses, network interruptions, and rate limits. The defaults are tuned for interactive use — short timeouts to keep the developer waiting as little as possible. But CI pipelines, batch processing, and complex reasoning tasks often need longer timeouts and more aggressive retry policies. A task that times out after 60 seconds of reasoning is wasted compute and a wasted API call.

Retry policies should distinguish between transient errors (rate limits, network blips) and permanent errors (invalid API key, malformed request). Retrying a permanent error wastes budget and time. Retrying a rate limit with exponential backoff is standard practice. The config.toml retry settings let you control max retries, initial delay, backoff multiplier, and which error codes trigger retries versus immediate failure.

# Timeout configuration by profile
[profile.default]
model = "codex-1"
# Default timeouts work for interactive use

[profile.ci]
model = "gpt-4.1"
approval = "full-auto"
# CI needs longer timeouts — no human waiting

[profile.deep-reasoning]
model = "o3"
reasoning_effort = "high"
# High reasoning tasks can take 2-3 minutes
# Ensure your timeout accommodates this

# Environment variables for retry control
# CODEX_MAX_RETRIES=3
# CODEX_RETRY_DELAY_MS=1000
# CODEX_RETRY_BACKOFF=2
# CODEX_TIMEOUT_MS=120000

Do This

  • Set profile-specific timeouts — interactive and CI have different needs
  • Use exponential backoff for rate limit retries (429 errors)
  • Log every timeout and retry for post-mortem analysis
  • Set a hard budget cap to prevent runaway retries from burning API credits

Avoid This

  • Use the same timeout for quick edits and deep reasoning tasks
  • Retry immediately on rate limits — you will hit the limit again
  • Set unlimited retries — a persistent error will drain your API budget
  • Ignore timeout patterns — frequent timeouts signal a model/task mismatch