http-client-divergence

The same HTTP response, sent to 12 different clients, produces 4 different results.

Not malformed responses — every case here is legal HTTP. The question is not whether your client survives garbage. It is whether you can predict what your client hands you when a real server does something ordinary and awkward, like returning 204, or a JSON body labelled text/html, or a truncated payload because the upstream process was killed mid-write.

16 of 19 measured cases produce different results depending on which client you used.

The one that should worry you

// server returns: 200, Content-Type: application/json, body: {"a":1,}   <- trailing comma
const res = await axios.get(url);

typeof res.data          // 'string'   <-- not 'object'
res.data                 // '{"a":1,}'
// axios did not throw. res.status is 200. Nothing is wrong, as far as your code can tell.

axios is the only client measured that silently hands back the raw string when JSON fails to parse. Every other client either raises or reports a parse failure. Code written as res.data.items.map(...) does not fail here with a parse error — it fails later, somewhere else, with undefined is not a function, and the stack trace points at the wrong line.

The same happens on a truncated body — which is exactly what a killed upstream process produces.

A second one, quieter and worse:

// server returns: 200, Content-Type: text/html, body: {"real":"json"}   <- valid JSON, wrong label
const res = await superagent.get(url);
res.body                 // {}     <-- your data is gone. No error. No warning.

superagent discards a valid JSON body when the content-type does not say JSON. Six APIs in the sibling api-false-success corpus switch content type on error, so this is not a hypothetical.

What was measured

| | | |---|---| | Cases | 19 — all legal HTTP | | Clients | 12 across Node and Python | | Cases where clients disagree | 16 (84%) | | Most distinct outcomes on one case | 4 | | Severity | 3 critical · 6 high · 6 medium · 1 low · 3 agree |

Clients: fetch (Node 24 built-in / undici 8.10.0), node-fetch 3.3.2, axios 1.19.0 (both default and validateStatus:null), got 15.1.0, ky 2.0.2, superagent 10.3.0, urllib (stdlib), http.client (stdlib), requests 2.34.2 (both plain and raise_for_status), httpx 0.28.1. Node v24.18.0, Python 3.14.6.

Selected results

| Case | What happens | |---|---| | 200 + invalid JSON | 8 clients report a parse failure · axios returns the raw string · got and superagent raise | | 200 + JSON labelled text/html | 11 clients parse it · superagent returns {} | | 200 + charset=ISO-8859-1 | 3 different results from identical bytes: requests honours the declared charset and decodes correctly · all 7 Node clients produce mojibake (U+FFFD), assuming UTF-8 · urllib, http.client and httpx raise UnicodeDecodeError | | 200 + UTF-8 BOM | 8 clients parse it fine · requests raises JSONDecodeError · got and superagent raise. A BOM is what Windows tooling emits by default | | 204 No Content | axios/got → '' · superagent → {} (so if (res.body) is truthy) · 8 others → parse failure | | 404 with a JSON error body | 9 clients hand you the parsed error · 3 raise, and the error details are harder to reach from the exception | | 301/302/307 | 11 follow the redirect · http.client does not, and returns the 3xx with an unparseable body |

Where the clients agree

200 with {"error":"validation failed","status":422} — all 12 clients hand you the object and none treats it as an error. Correctly: HTTP said 200. No client can save you from this, which is what the sibling package exists to document.

Use

npm install http-client-divergence

const d = require('http-client-divergence');

d.meta.diverging_case_count;        // 16
d.bySeverity('critical');           // the 3 that silently corrupt data
d.outliers('superagent');           // cases where superagent alone behaves that way
d.compare('axios', 'fetch(builtin)'); // every case where they differ
d.getCase('200-invalid-json').safe_pattern;

Every case carries a hand-written meaning (what it does to your code) and safe_pattern (how to write code that survives it). Those are the part that cannot be generated — the matrix can be, but knowing which divergence silently corrupts data and which is cosmetic requires reading each one.

forClient() throws on an unknown client name rather than returning an empty array. An empty array would be indistinguishable from "this client behaved well", which is the exact failure shape this dataset documents. It seemed wrong to ship it.

Reproduce it

The harness is in harness/ and takes under a minute. It is included because a measurement you cannot re-run is an assertion.

python harness/server.py 8731 &     # emits the 19 responses
node   harness/probe_node.mjs       # 7 Node clients
python harness/probe_py.py          # 5 Python clients
python harness/report.py            # divergence table

Limits, stated plainly

• One date, one set of versions, one platform. Client behaviour changes. measured_on is 2026-08-04; the versions are listed above; the platform was Windows. Re-run the harness.
• 19 cases is a demonstration, not coverage. There are many more legal-but-awkward responses than these. Absence of a case here means not measured, not safe.
• Only the JSON path was measured, using each client's idiomatic JSON call. Streaming, multipart, compression, HTTP/2, cookies, proxies and connection reuse were not tested and are not claimed.
• Header-level semantics were not measured. The duplicate-header case checks the body only, and is marked as such in the data. Do not cite it for header joining.
• Three cases that appear to diverge in the raw output do not. JS and Python render the same object differently. The reported figure of 16 is after canonicalising that away — the naive count is 19 of 19, and it is wrong.
• Nothing here is a bug report. Every client's behaviour is defensible in isolation. The finding is that they differ, and that almost nobody knows by how much.

Licence

CC-BY-4.0. Measurements are facts; the arrangement and the hand-written notes are the contribution.