ERROR CODES / ENGLISH

API timeout: the request did not complete in time

Five causes of AI API timeouts, from client thresholds that are too short to slow upstreams, with settings for common clients.

Reviewed 2026-11-13 · ERROR CODES / ENGLISH · Chinese detail: 完整中文页

What it means

The request did not receive a complete response within the configured time. Raise the timeout threshold first, then check the network path. Most timeouts come from client settings that are too short, not from a service outage.

Error: The operation timed out.
FetchError: request to https://api.example.com/v1/messages failed, reason: connect ETIMEDOUT
{"error":{"message":"upstream request timeout","type":"new_api_error"}}

Common causes

Share	Cause
40%	Client timeout set too short (the default 30s is not enough for long answers)
30%	Upstream under high load, responding slowly
15%	Network path problem (cross-border, proxy)
10%	Relay gateway timeout is shorter than your own
5%	The streaming response was interrupted mid-way

How to confirm

Measure where the time goes:

curl -o /dev/null -s -w "connect: %{time_connect}s\nfirst byte: %{time_starttransfer}s\ntotal: %{time_total}s\n" \
  https://api.example.com/v1/models -H "Authorization: Bearer $KEY"

High time_connect, so the problem is DNS or the network path
High time_starttransfer, so server-side processing is slow

Fix

Raise the timeout:

Client	How to set it
OpenAI SDK	`client = OpenAI(timeout=120)`
Anthropic SDK	`client = Anthropic(timeout=120)`
Node fetch	`AbortSignal.timeout(120_000)`
curl	`--max-time 180`
Cursor	Find Network / Timeout in settings

Long answers need 120 seconds or more. Generating 4000 tokens on a slow channel can exceed 60 seconds.

If it still fails

Symptom	Responsible party
Short requests work, long answers time out	Your timeout threshold
All requests time out	Network or the site is down
Timeouts only at peak hours	Upstream load
Switching network fixes it	Your link

General guidance, not a statement about any specific provider. For measured data, see the relay directory and method.