Codex 'Request Timed Out' Errors: The Complete Field Guide

"Codex request timed out." If you've used OpenAI's Codex CLI long enough, you've seen this error — probably more than once. Here's the part most write-ups skip: it is not a single bug. It is a category of symptoms with at least eight distinct root causes, and a fix only works when you have correctly identified which layer you're in. This guide gives you the full taxonomy, a 30-second diagnosis tree, and concrete, copy-paste fixes for every cause.

Why classify before fixing

A timeout means: the request was sent, but no complete response arrived within the allotted window. That "no response" can happen at any hop — before the request leaves your machine (DNS failure), while establishing the connection (TCP can't connect), during the TLS handshake (SNI blocked), in transit (packets dropped or reset), at the server (overloaded), or while waiting (the timeout was simply too short).

The cost of guessing wrong is real. Fixing your proxy does nothing for DNS pollution. Switching proxy nodes does nothing for an oversized request. Raising the timeout does nothing for rate limiting. Classify first, and your hit rate goes up dramatically.

First, split into two layers: client timeout vs server timeout

• Client timeout — your machine gave up waiting. Signature errors: Connection timeout after 30000ms, request timed out, fetch failed. Usually a network path or configuration problem.
• Server timeout — the request reached the server, but the response was slow. Signature: the error takes a long time to appear, it clusters around peak hours, and requests immediately before and after succeed.

A single curl call separates the two:

curl -sS -o /dev/null -w "HTTP %{http_code} in %{time_total}s\n" \
  https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"

• A 401 or 200 within a few seconds: the endpoint is healthy — the problem is your specific request or configuration.
• A hang or connection error: the network can't reach the endpoint at all.
• Success, but slow (several seconds): server latency — raise your timeout and add retries.

The eight-cause taxonomy

#	Cause	One-line symptom	Fastest diagnosis
1	Network layer	Can't connect at all; curl times out / returns 000	curl -I api.openai.com
2	Proxy configuration	Browser works, terminal doesn't	Check HTTPS_PROXY in your shell
3	DNS	getaddrinfo ENOTFOUND	nslookup api.openai.com
4	The proxy tool itself	Proxy is running but the node is dead	curl -x ... through the proxy
5	Codex server	Slow or hanging during peak hours	Check if errors cluster in peak hours / popular models
6	Request body too large	Times out on long chats or big files	Shrink the context and retry
7	Concurrency limits	Timeouts after high-frequency calls	Look for 429 in the usage panel
8	Client bug	Old version, expired token, sandbox hang	codex --version + re-login

30-second diagnosis tree

1. Run curl -I --max-time 20 https://api.openai.com/v1/models:
   • Timeout or 000 → go to step 2.
   • Fast 401 → the network is fine; jump to step 4.
2. Are you connecting directly, or through a proxy?
   • Direct connection times out → likely the network layer or DNS (cause 1 or 3).
   • Through a proxy → test through the proxy with curl -x, to distinguish a dead node (cause 4) from a wrong proxy config (cause 2).
3. Does the error mention ENOTFOUND? → DNS (cause 3).
4. Network is fine but it still times out:
   • Only on long conversations or large files → cause 6.
   • After a burst of high-frequency calls → cause 7.
   • Peak hours, error after a long wait → cause 5.
   • Old version, fixed timeout a few minutes into a run, sandbox command stuck → cause 8.

The fixes, cause by cause

1. Network layer

Symptoms: connect ETIMEDOUT, curl returns 000, all outbound requests feel slow.

Diagnose:

curl -I --max-time 20 https://api.openai.com/v1/models
npm ping   # is npm slow too? if so, it's the whole machine's network

Fix: confirm the network itself; switch to a different network; or point Codex at an OpenAI-compatible gateway endpoint your network can actually reach.

2. Proxy configuration

Symptoms: the browser reaches OpenAI fine, but the terminal CLI times out. A CLI frequently does not read your system proxy.

Diagnose:

env | grep -i proxy   # are the proxy variables set in your shell at all?

Fix:

export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
codex

(Replace 127.0.0.1:7890 with your local proxy address.) Note the source's warning: a misconfigured proxy is worse than no proxy — every request goes into a dead tunnel and waits. For a clean test, unset all proxy variables and try once without them.

3. DNS pollution / resolution failure

Symptoms: getaddrinfo ENOTFOUND, fetch failed.

Diagnose:

nslookup api.openai.com   # inspect the returned IPs for anything suspicious
export NODE_OPTIONS=--dns-result-order=ipv4first   # if it looks like an IPv6 ordering issue

Fix: switch your DNS resolver (for example 1.1.1.1 or 8.8.8.8); or switch to an endpoint whose domain isn't polluted.

4. The proxy tool itself

Symptoms: the proxy process is running and the port is correct, but requests still time out.

Diagnose — test through the proxy:

curl -x http://127.0.0.1:7890 -I --max-time 20 https://api.openai.com/v1/models

Fix: a 401 means the node is usable; a timeout means the node itself is rate-limited or down. Switch nodes, or switch proxy tools.

5. Codex server overload

Symptoms: errors cluster in peak hours and around popular models; the failure takes a long time to appear; requests right before and after succeed.

Fix: this is not a network problem. Increase the timeout, add retries, or route through an upstream gateway with spare capacity to spread the peak load.

6. Request body too large

Symptoms: timeouts appear after long conversations or after stuffing in large files; shrinking the context makes it recover.

Fix: trim the context (send only task-relevant code); run codex logout && codex login to clear the local session cache; restart the local daemon.

7. Concurrency limits

Symptoms: timeouts start after high-frequency calls; the usage panel shows 429 or rate-limit warnings.

Fix: not a network problem. Lower concurrency, wait for the quota window to reset, upgrade your tier, or spread load across multiple upstreams through a gateway.

8. Client bug

Symptoms: timeouts that only appear in old versions; a fixed timeout a few minutes into a run; a sandbox where even ls hangs (exit 124).

Fix:

npm install -g @openai/codex@latest
codex logout && codex login
# macOS: when the sandbox silently blocks network access:
codex --sandbox danger-full-access "your prompt"

A one-line memory

• Causes 1 / 3 / 4 (network, DNS, proxy tool) → change the path.
• Cause 2 (proxy config) → change the variable.
• Causes 5 / 7 (server, concurrency) → adjust upstream or quota.
• Cause 6 (oversized request) → lighten the load.
• Cause 8 (client bug) → upgrade the version.

The priority checklist

1. curl to locate (1 min) — separate client / server / network-unreachable.
2. Clear proxy variables and test once (1 min) — rule out "misconfigured proxy is worse than none."
3. Update the CLI and re-login (2 min) — rule out old-version bugs and expired tokens.
4. Raise the timeout and add retries (SDK users) — rule out "waited too short."
5. Trim the context and clear the session cache — rule out "request too big."
6. Check the usage panel — rule out rate limits and quotas.
7. Switch to a reachable gateway endpoint — eliminates the network, DNS, and proxy causes in one move.

Prevention

• Prefer a gateway endpoint for the long term. Point OPENAI_BASE_URL at an OpenAI-compatible endpoint your network can reach natively — one that supports /v1/responses — which removes DNS pollution, SNI blocking, and dead proxy nodes at the source. (For example, some providers sell gateway endpoints reachable from mainland China; one such OpenAI-compatible provider is TeamoRouter. The mechanism, not the vendor, is the point: reachable endpoint, native protocol, no proxy tunnel.)
• Set sensible timeouts and retries. 30–60s for short interactive tasks; 120–300s with 2–3 retries for long agent tasks.
• Control concurrency. Don't let multiple tools share one key and hammer it into a 429.
• Keep the CLI current. Timeout-class bugs tend to get fixed in releases.
• Watch the sandbox. On macOS, if shell commands inside Codex time out, check the sandbox network switch first.

The honest note: what's common vs rare

The source material here was written from a mainland China network context, and its frequency claims come with that caveat. What it actually states: in that environment, the most common causes are the network layer, proxy configuration, and DNS (causes 1 / 2 / 3), and they often appear together — which is exactly why "switch to a reachable gateway endpoint" clears all three at once. Causes 6, 7, and 8 (oversized requests, concurrency, client bugs) are network-independent — a gateway won't fix those, and they have to be handled per cause. Cause 8 is the one that mostly disappears once you update the CLI, so for anyone current it's effectively rare.

Your own mix will differ if your network is unrestricted — peak-hour server overload (cause 5) and rate limits (cause 7) tend to move up the list. The frequency ranking matters less than the classification: diagnose the layer, then apply the fix for that layer.

Two more source-stated behaviors worth internalizing:

• Intermittent timeouts usually point to load, rate limiting, or route jitter — not a hard configuration error. Check rate limiting first.
• A VPN is not a permanent fix. It helps if the root problem is routing, but a jittery VPN tunnel itself causes timeouts. A stable, reachable gateway endpoint beats a tunnel.

Also keep the distinction from the source's FAQ: a timeout ("request sent, no response received") is not the same as being blocked ("request rejected: region / IP / auth"). Timeouts are a network-and-timeout problem; blocks need a different access method. A gateway resolves most of the former, and for the latter you need a compliant access path.

Conclusion

"Codex request timed out" is not one error — it's eight, and each has a different fix. Run the 30-second curl diagnosis to find your layer, walk the priority checklist in order, and use a reachable gateway endpoint plus sane timeout values to stop most of it from coming back. Classify first, fix second, and the error stops being a guessing game.