`APIConnectionTimeoutError` — the Anthropic or OpenAI TypeScript SDK gave up waiting on a request

APIConnectionTimeoutError: Request timed out.

(Assembled by us from the class name and the default message quoted as source below; how your runtime prints it may differ. The OpenAI SDK’s client also builds one longer variant of the message, shown in its section.)

Two SDKs share this name. In the Anthropic TypeScript SDK and in the OpenAI Node SDK, APIConnectionTimeoutError is a subclass of APIConnectionError whose default message is Request timed out.. The Anthropic SDK throws it at one line of its client, when a request’s fetch fails in a way the SDK reads as a timeout and no retries are left. The OpenAI SDK builds it at several places in its client: the same fetch-failure case, a deadline on reading a response body, and two more paths used only with X.509 workload identity. Every claim about the libraries below is read off the TypeScript source of anthropics/anthropic-sdk-typescript at tag sdk-v0.133.0 and openai/openai-node at tag v7.32.0, fetched on 10 October 2026, with the line of each quote given; where we draw a conclusion from those lines rather than quote them, we say so.

What it is: in both SDKs, export class APIConnectionTimeoutError extends APIConnectionError { in src/core/error.ts; APIConnectionError extends APIError, which extends AnthropicError or OpenAIError, which extends Error.

Where: Anthropic — src/client.ts line 1396, after the no more retries left log lines. OpenAI — src/client.ts lines 1494, 1536, 1578, 1801, 1806, 1808 and 2144 construct it; the line-1801/1806 error is thrown at line 1810.

What to do: set timeout and maxRetries on the client or on the single request; if the timer is not yours, look at the cause (a connect timeout, or Node.js fetch’s own header timeout on the OpenAI side); for long Anthropic generations, stream (our reading).

The class, in both SDKs

The Anthropic SDK’s src/core/error.ts, lines 125–129:

export class APIConnectionTimeoutError extends APIConnectionError { constructor({ message }: { message?: string } = {}) { super({ message: message ?? 'Request timed out.' }); } }

The OpenAI SDK’s src/core/error.ts has the same five lines at 121–125. In both files APIConnectionError extends APIError<undefined, undefined, undefined> (Anthropic line 116, OpenAI line 112) with the default message 'Connection error.', and APIError closes its type parameters with > extends AnthropicError { (Anthropic line 10) or > extends OpenAIError { (OpenAI line 10); line 4 of each file is export class AnthropicError extends Error {} or export class OpenAIError extends Error {}. So catch code that checks for APIConnectionError also catches this (our reading). APIError’s constructor stores this.status = status; (Anthropic line 32, OpenAI line 26), and APIConnectionError passes undefined, so err.status is undefined; with no status and no error body, makeMessage returns the message as given (Anthropic lines 40–59, OpenAI lines 37–56), so err.message is Request timed out. unless a site passed another (our reading).

Anthropic SDK: where it is thrown

A grep of the Anthropic SDK’s src/client.ts finds APIConnectionTimeoutError on two lines: the throw at 1396 and a static re-export at 1846. The throw is in makeRequest (line 1296). It calls fetchWithTimeout (line 1329), which arms const timeout = setTimeout(abort, ms); (line 1539) around the underlying fetch. When the fetch fails, the SDK first throws APIUserAbortError if your own signal aborted (lines 1338–1340), then decides whether the failure was a timeout, lines 1345–1347:

const isTimeout = isAbortError(response) || /timed? ?out/i.test(String(response) + ('cause' in response ? String(response.cause) : ''));

The comments above it (lines 1341–1344) say this is to detect native connection timeout errors, citing Deno’s and undici’s messages. So the SDK’s own timeout firing (an abort) counts, and so does any fetch error whose text or cause mentions a timeout, such as a connect timeout (our reading). If retries remain, it logs connection ${isTimeout ? 'timed out' : 'failed'} - ${retryMessage} (line 1368) and retries (line 1380). Otherwise it logs connection ${isTimeout ? 'timed out' : 'failed'} - error; no more retries left (line 1383), and lines 1395–1397 are:

if (isTimeout) { throw new Errors.APIConnectionTimeoutError(); }

So in this SDK the error you catch is thrown once retries are exhausted, with the default message and no cause set on it (our reading of line 1396). Retries are skipped when the request body is a stream: maxRetries = 0; under if (this.isStreamBody(options.body)) { (lines 1303–1304).

Anthropic SDK: the timeout and retry settings

Default timeout: static DEFAULT_TIMEOUT = 600000; // 10 minutes (line 1841), used by this.timeout = options.timeout ?? BaseAnthropic.DEFAULT_TIMEOUT /* 10 minutes */; (line 831). The option’s comment (lines 652–660) says it is per single request and that request timeouts are retried by default, so you may wait much longer than this timeout.
Default retries: this.maxRetries = validatePositiveInteger('maxRetries', options.maxRetries ?? 2); (line 840).
Per request: RequestOptions in src/internal/request-options.ts has maxRetries?: number; (line 80) and timeout?: number; (line 90), and the client prefers them: options.maxRetries ?? this.maxRetries (line 1302), options.timeout = options.timeout ?? this.timeout; (line 1717).
Long requests: the client’s calculateNonstreamingTimeout (line 1683) throws an AnthropicError — a different error — with the text Streaming is required for operations that may take longer than 10 minutes. (line 1690). Where it is called is not in the files we fetched.
Catching it: static APIConnectionTimeoutError = Errors.APIConnectionTimeoutError; (line 1846) sits in class BaseAnthropic (line 735), which export class Anthropic extends BaseAnthropic { (line 1866) extends, so err instanceof Anthropic.APIConnectionTimeoutError works (our reading).

OpenAI SDK: where it is built and thrown

A grep of the OpenAI SDK’s src/client.ts finds new Errors.APIConnectionTimeoutError( at lines 1494, 1536, 1578, 1801, 1806, 1808 and 2144, an instanceof check at 1589 and a static re-export at 2416. By where they sit:

A failed fetch (lines 1793–1811), in makeRequest (line 1604). The same isTimeout test as the Anthropic SDK’s, at lines 1747–1749. The request is retried while retriesRemaining &&, !hasStreamingBody && and, under X.509 authentication, only for an error the SDK treats as transient (lines 1750–1754). Otherwise it logs the terminal message from lines 1775–1777:

const terminalMessage = hasStreamingBody ? 'error; streaming body cannot be retried' : 'error; no more retries left';

and, if (isTimeout) { (line 1793), builds the error with the default message, or with this one when the fetch error’s cause has code UND_ERR_HEADERS_TIMEOUT (lines 1795–1799), lines 1802–1804:

message: 'Request timed out. Node.js fetch timed out waiting for response headers; ' + 'configure a matching undici fetch and fetchOptions.dispatcher with an Agent whose headersTimeout is at least the SDK timeout.',

It then throws throw Object.assign(timeoutError, { cause: response }); (line 1810), so here err.cause holds the original fetch error; under X.509 authentication it throws a fresh default one instead (line 1808).

Reading the response body (lines 1490–1537), in parseResponseWithTimeout (line 1450). For a response that is not props.options.stream ||, not binary, not a 204 and not empty (lines 1451–1458), body parsing races a timer set to what is left of the timeout since the request started (lines 1471–1473, 1491–1495). When it fires, line 1494 rejects with the error; the catch block retries, unless no retries remain or the request body was a stream (lines 1522–1535), in which case line 1536 throws a new one. So the line-1494 instance itself does not reach you (our reading).
X.509 workload identity only. Line 1578, in readX509ResponseError (line 1559), when reading an error body outlives the deadline (line 1589 is that function’s own instanceof check); and line 2144, in retryRequest (line 2097), when the wait before a retry would reach the deadline: if (timeoutMillis >= remaining) { (line 2143). If you do not use X.509 workload identity, these two do not apply (our reading).

OpenAI SDK: the timeout and retry settings

Default timeout: static DEFAULT_TIMEOUT = 600000; // 10 minutes (line 2411), used by this.timeout = options.timeout ?? OpenAI.DEFAULT_TIMEOUT; /* 10 minutes */ (line 625).
Node.js fetch has its own timers. The option’s comment, lines 371–373: Node.js fetch enforces independent response-header and body-inactivity timeouts, typically / defaulting to five minutes, even when this timeout is longer. It goes on to show an undici Agent with headersTimeout and bodyTimeout (line 383).
Default retries: this.maxRetries = this.#normalizeRetries(options.maxRetries); (line 635), where anything but a safe non-negative integer becomes 2 (line 1026).
Per request: RequestOptions in src/internal/request-options.ts has maxRetries?: number; (line 44) and timeout?: number; (line 54); the body timer reads attempt?.timeout ?? props.options.timeout ?? this.timeout (line 1462).
Catching it: static APIConnectionTimeoutError = Errors.APIConnectionTimeoutError; (line 2416) is in export class OpenAI { (line 471), so err instanceof OpenAI.APIConnectionTimeoutError works (our reading).

In the field

In jt-mchorse/ai-app-integration-tests#163, measured with @anthropic-ai/sdk@0.96.0 (an older version than the one read above) and a client built with maxRetries: 0, a server that accepts the connection and never answers gave:

accepts, never answers (timeout 300) -> 1 call, APIConnectionTimeoutError "Request timed out." classify=hard

One call, because retries were off. The issue is about the reporter’s own retry classifier, which matched on the message and missed the class.

What to do

If you set a short timeout, raise it, on the client or for the one request that needs it; both SDKs take timeout in milliseconds in either place (our reading).
If you are near the 10-minute default with an Anthropic call, the client’s own text says streaming is required past 10 minutes; stream the request rather than raise the limit (our reading). On the OpenAI side, the body-read timer in parseResponseWithTimeout is skipped for stream requests (line 1452).
If the message mentions Node.js fetch and response headers (OpenAI only), do what it says: pass an undici fetch and a fetchOptions.dispatcher Agent whose headersTimeout is at least the SDK timeout.
If it fires long before your timeout, the timer was probably not yours: the SDKs also count fetch errors whose text says “timed out”, such as a connect timeout. Look at err.cause (OpenAI, line 1810) or the SDK’s debug log, and check the network path (our inference).
Retries: maxRetries sets how many more tries a timeout gets before you see this error; each try can take the full timeout, so raising it lengthens the worst case (our reading of the option comment above). Setting it to 0 surfaces the first timeout (our reading).

import Anthropic from '@anthropic-ai/sdk'; import OpenAI from 'openai'; // Our sketch: one deadline and retry count per client, and one check for either SDK's timeout. export const anthropic = new Anthropic({ timeout: 5 * 60 * 1000, maxRetries: 3 }); export const openai = new OpenAI({ timeout: 5 * 60 * 1000, maxRetries: 3 }); export function isRequestTimeout(err: unknown): boolean { return err instanceof Anthropic.APIConnectionTimeoutError || err instanceof OpenAI.APIConnectionTimeoutError; }

(Our sketch, not library code, and not run against your version. The two constructors read their API keys from the environment as usual; the numbers are placeholders, not advice.)

What is behind this site

There is a written guide: the step-and-turn arithmetic as a formula you can run against a brief before you launch it, why raising a cap does not finish the job, and batch.py, one standard-library file that collapses a per-item loop into a single pass — fewer turns, which means fewer final calls made from an unfinished transcript when a run hits its cap. It is $19, on a storefront that delivers the files automatically and carries a 30-day money-back guarantee (checked 7 October 2026). One working way to pay today is 19 USDC on Base, and delivery is manual: you email the transaction hash and the files come back as a reply. This page is free, ungated, and sells nothing on its own.

The short version: APIConnectionTimeoutError (Request timed out.) is the Anthropic and OpenAI TypeScript SDKs’ subclass of APIConnectionError for a request that timed out; it carries no HTTP status. The Anthropic SDK throws it after the no more retries left log; the OpenAI SDK throws it after retries run out or when a streaming request body cannot be retried, and on its X.509 paths. Both default to a 10-minute timeout and 2 maxRetries, settable per client or per request.

Nearby

ModelTimeoutError — the OpenAI Agents SDK’s deadline on one model call, set by ModelSettings.timeout; this one is the HTTP client’s own deadline, inside the Anthropic or OpenAI TypeScript SDK.
overloaded_error — Anthropic’s HTTP 529, an answer from the server with a status; this one is the SDK’s own timeout, and its status is undefined.
McpError — the MCP Python SDK’s error, timeouts included, for a request to an MCP server; this one is a TypeScript SDK’s error for a call to the Anthropic or OpenAI API.

This page counts anonymous readership with one counter, the file at /measure.js, and each of the events below is sent at most once per load. Once the page is ready it sends one view event. With it go the page path, the domain of the page you came from — only the domain, and nothing at all if you came from this site — how long the page has been open, counting only the time it was actually in front of you and not the time it sat in a background tab, whether you have scrolled, and any campaign or outreach code in the link you followed. A second event, which we call a human candidate, is sent only once the page has also received a real input event from you — a mouse movement, a touch, a scroll or a key press — and has been visible in the foreground for ten seconds in all; a program that fetches the page, or opens it and sits there, cannot produce one. A third, “engaged”, is stricter still: it is sent only after the human-candidate event, once the page has been in front of you for ninety seconds in all and you have scrolled far enough to reach a marker we put where the explaining part of this page ends; a reader who stops short of that marker never produces one. The second and third events carry the same fields as the first. If you switch away from the tab or close it, an event that has just become due may be sent as you leave. If this page has a button or a copy control that says it records a click, pressing it sends the name of that event and nothing else. Following a link to buy the guide sends one further event, also at most once per load, carrying that event’s name and a single word for which of the two checkouts you were sent to — the Gumroad listing or the payment page on this site — and nothing else: not the address you followed, not which page you were reading, not how long you had been there. Everything is sent to this site only, with no cookie attached. No cookie is read or written, nothing is put in your browser’s local or session storage, and no identifier is made from your device. Earlier versions of this page kept the campaign codes of your first visit in local storage under the name llab_attr; this page neither reads nor deletes that entry, so if it is there it stays until you clear this site’s data. An outreach code is minted per recipient, which would let us tell one reader from another; it is sent with each event and, unlike on earlier versions of this page, it is no longer removed from the address bar after it is read — if you copy the address, the code goes with it. Earlier versions also asked this domain for Vercel’s analytics script at /_vercel/insights/script.js, which on 26 September 2026 returned HTTP 404 on every host we publish; this page no longer asks for it. Your browser and the network attach things the page does not send: the identification string your browser gives, your IP address and the time of the request. The host that serves this page keeps its own request logs; those are its record and not ours.

APIConnectionTimeoutError — the Anthropic or OpenAI TypeScript SDK gave up waiting on a request