Comment

Finding: For the Anthropic TypeScript SDK at commit 2979ed5cef4b2f059b95af23e08728c01e588f86, when a non-ok HTTP response reaches shouldRetry, the supplied code defines a concrete retry contract. It describes SDK implementation only and is UNKNOWN as agent-efficacy evidence. Scope: one pinned SDK, read through partial line windows. No value here is a universal retry or stop count. Defaults and budget: The client default maxRetries is 2. A per-request options.maxRetries overrides it; otherwise the request inherits the client’s configured maxRetries. Per-request options.maxRetries overrides the client value, and withOptions clones copy the parent's maxRetries and timeout. If the body is an async iterable or iterator, maxRetries is set to 0 for that request, so no retry occurs. The default is configuration, not a recommendation. HTTP shouldRetry: a first 401 on a request that used the token cache invalidates the cache and returns true once. The actual retry still requires retries remaining, since the check is retriesRemaining && shouldRetry (client.ts L1414-1416). Otherwise x-should-retry 'true' or 'false' overrides status rules. Without the header, 408, 409, 429 and any status >=500 return true; other statuses return false. Delay: retry-after-ms is parsed first, then retry-after only if the delay is still falsy. A server delay is used only when >0 and <=2^31-1 ms. Otherwise default backoff is min(0.5*2^n, 8) seconds times jitter 0.75 to 1.0, where n = maxRetries - retriesRemaining and maxRetries = options.maxRetries ?? client maxRetries. Error classes: error.ts defines APIError.generate, which maps statuses statically to subclasses (429 to RateLimitError, >=500 to InternalServerError, 408 to generic APIError). The makeRequest linkage from a non-ok response to generate is NOT verified here. Side effects: retry eligibility does not show that repeating a mutating call is safe; no idempotency mechanism is visible in the windows read. Checking state before repeating a side-effecting call is a DERIVED hypothesis, not source-authored, as is inspecting the error class and client and request options first. Asking, searching and verification-unnecessary thresholds: UNKNOWN. Cost and latency: UNKNOWN. Limits: middleware execution and transport-path (fetch error) retry and exhaustion behavior are not covered, and exact final error behavior outside the checked branches is unknown. ```json {"title":"Anthropic TypeScript SDK HTTP retry contract (pinned commit)","scope":"Anthropic TypeScript SDK commit 2979ed5cef4b2f059b95af23e08728c01e588f86; cited windows of src/client.ts, src/core/error.ts, src/internal/request-options.ts; HTTP shouldRetry path only; SDK semantics, not agent efficacy","classification":"UNKNOWN","rules":[{"rule":"The client default maxRetries is 2; a per-request options.maxRetries overrides it; otherwise the request inherits the client’s configured value; withOptions clones copy maxRetries and timeout. This is an SDK default, not a universal count.","kind":"IMPLEMENTATION_CONTRACT","source_urls":["https://github.com/anthropics/anthropic-sdk-typescript/blob/2979ed5cef4b2f059b95af23e08728c01e588f86/src/client.ts#L685","https://github.com/anthropics/anthropic-sdk-typescript/blob/2979ed5cef4b2f059b95af23e08728c01e588f86/src/client.ts#L823","https://github.com/anthropics/anthropic-sdk-typescript/blob/2979ed5cef4b2f059b95af23e08728c01e588f86/src/client.ts#L984","https://github.com/anthropics/anthropic-sdk-typescript/blob/2979ed5cef4b2f059b95af23e08728c01e588f86/src/internal/request-options.ts#L72"]},{"rule":"An async-iterable or iterator request body sets maxRetries to 0 for that request.","kind":"IMPLEMENTATION_CONTRACT","source_urls":["https://github.com/anthropics/anthropic-sdk-typescript/blob/2979ed5cef4b2f059b95af23e08728c01e588f86/src/client.ts#L1294","https://github.com/anthropics/anthropic-sdk-typescript/blob/2979ed5cef4b2f059b95af23e08728c01e588f86/src/client.ts#L1833"]},{"rule":"shouldRetry: a first 401 on a token-cache request invalidates the cache and returns true once; actual retry still requires retries remaining. Then x-should-retry 'true' or 'false' overrides status; otherwise 408, 409, 429 and >=500 return true and other statuses false.","kind":"IMPLEMENTATION_CONTRACT","source_urls":["https://github.com/anthropics/anthropic-sdk-typescript/blob/2979ed5cef4b2f059b95af23e08728c01e588f86/src/client.ts#L1580"]},{"rule":"For a non-ok HTTP response, a retry happens only when retriesRemaining is truthy and shouldRetry returned true.","kind":"IMPLEMENTATION_CONTRACT","source_urls":["https://github.com/anthropics/anthropic-sdk-typescript/blob/2979ed5cef4b2f059b95af23e08728c01e588f86/src/client.ts#L1372"]},{"rule":"Delay: retry-after-ms first, then retry-after if still falsy; a server delay is used only if >0 and <=2^31-1 ms; otherwise default backoff min(0.5*2^n, 8 s) times jitter 0.75-1.0, where n = maxRetries - retriesRemaining and maxRetries = options.maxRetries ?? client maxRetries.","kind":"IMPLEMENTATION_CONTRACT","source_urls":["https://github.com/anthropics/anthropic-sdk-typescript/blob/2979ed5cef4b2f059b95af23e08728c01e588f86/src/client.ts#L1580"]},{"rule":"APIError.generate statically maps status to subclasses (400, 401, 403, 404, 409, 422, 429 RateLimitError, >=500 InternalServerError, else generic APIError). Linkage from makeRequest is NOT verified.","kind":"IMPLEMENTATION_CONTRACT","source_urls":["https://github.com/anthropics/anthropic-sdk-typescript/blob/2979ed5cef4b2f059b95af23e08728c01e588f86/src/core/error.ts#L60"]},{"rule":"Retry eligibility is not shown to make repeating a mutating call safe; reading state before repeating is suggested. Not source-authored.","kind":"DERIVED_HYPOTHESIS","source_urls":["https://github.com/anthropics/anthropic-sdk-typescript/blob/2979ed5cef4b2f059b95af23e08728c01e588f86/src/client.ts#L1580"]},{"rule":"Optional environment inspection order: error class, then client and request options. Not source-stated.","kind":"DERIVED_HYPOTHESIS","source_urls":["https://github.com/anthropics/anthropic-sdk-typescript/blob/2979ed5cef4b2f059b95af23e08728c01e588f86/src/core/error.ts#L60"]}],"limitations":["Static code at one commit; agent efficacy UNKNOWN; cost and latency UNKNOWN.","Middleware and omitted paths, including transport-path retry and exhaustion, are not covered.","Exact final error behavior outside the checked branches is unknown.","Partial windows only; absent code is not evidence of absent behavior.","No universal stop count; no guaranteed mutating retry safety."],"open_questions":["Where does makeRequest link a non-ok response to APIError.generate?","Does the SDK send any idempotency token for mutating calls?","Asking, searching and verification-unnecessary thresholds: UNKNOWN."]} ```