acl-2909: retry on ECONNRESET / EPIPE / EAI_AGAIN

Expands HttpClient's retryable axios error code allowlist so transient
transport failures (TCP RST mid-flight, broken pipe, transient DNS) are
retried instead of bubbling up as hard errors on the first attempt.

Aligns deepl-node behavior with deepl-python, which retries any
requests.exceptions.ConnectionError.

Motivating incident: ritabot org saw four parallel /v2/translate calls
fail with ECONNRESET ("socket hang up") on 2026-04-18 22:51:27 UTC; the
SDK classified all four as non-retryable and surfaced them as user-
visible errors. With this change, the SDK would have retried.

The retryable-codes set is exported as @internal so the contract is
testable; ECONNREFUSED, ENOTFOUND, and CERT_HAS_EXPIRED remain non-
retryable.

Author: dfenster

CHANGELOG.md

@@ -5,6 +5,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Fixed
+- HTTP requests that fail with `ECONNRESET`, `EPIPE`, or `EAI_AGAIN` are now
+  retried. Previously these were classified as non-retryable, surfacing
+  transient transport failures (e.g. stale keep-alive sockets) as hard errors
+  on the first attempt. Behavior now aligns with deepl-python.
+
 ### Security
 - Bump follow-redirects to 1.16.0 due to GHSA-r4q5-vmmm-2653.
 

src/client.ts

@@ -15,6 +15,19 @@ import * as http from 'http';
 
 type HttpMethod = 'GET' | 'DELETE' | 'POST' | 'PUT' | 'PATCH';
 
+/**
+ * Axios error codes for transient transport-level failures that should be retried.
+ * Mirrors deepl-python's broader ConnectionError retry coverage.
+ * @internal
+ */
+export const RETRYABLE_AXIOS_ERROR_CODES = new Set([
+    'ETIMEDOUT',
+    'ECONNABORTED',
+    'ECONNRESET',
+    'EPIPE',
+    'EAI_AGAIN',
+]);
+
 const axiosInstance = axios.create({
     httpAgent: new http.Agent({ keepAlive: true }),
     httpsAgent: new https.Agent({ keepAlive: true }),
@@ -261,9 +274,7 @@ export class HttpClient {
 
             const error = new ConnectionError(`Connection failure: ${message}`);
             error.error = axiosError;
-            if (axiosError.code === 'ETIMEDOUT') {
-                error.shouldRetry = true;
-            } else if (axiosError.code === 'ECONNABORTED') {
+            if (axiosError.code !== undefined && RETRYABLE_AXIOS_ERROR_CODES.has(axiosError.code)) {
                 error.shouldRetry = true;
             } else {
                 logDebug('Unrecognized axios error', axiosError);

tests/client.test.ts

@@ -5,6 +5,7 @@
 import * as deepl from 'deepl-node';
 
 import { exampleText, makeDeeplClient, makeTranslator } from './core';
+import { RETRYABLE_AXIOS_ERROR_CODES } from '../src/client';
 import log from 'loglevel';
 
 jest.mock('loglevel', () => ({
@@ -17,6 +18,26 @@ jest.mock('loglevel', () => ({
 }));
 
 describe('client tests', () => {
+    describe('retry classification', () => {
+        it.each([
+            ['ETIMEDOUT'],
+            ['ECONNABORTED'],
+            ['ECONNRESET'],
+            ['EPIPE'],
+            ['EAI_AGAIN'],
+        ])('treats axios error code %s as retryable', (code) => {
+            expect(RETRYABLE_AXIOS_ERROR_CODES.has(code)).toBe(true);
+        });
+
+        it.each([
+            ['ENOTFOUND'],
+            ['ECONNREFUSED'],
+            ['CERT_HAS_EXPIRED'],
+        ])('does not treat axios error code %s as retryable', (code) => {
+            expect(RETRYABLE_AXIOS_ERROR_CODES.has(code)).toBe(false);
+        });
+    });
+
     describe('log debug', () => {
         beforeEach(() => {
             jest.clearAllMocks();