Node.js 18 built-in fetch: Service timeouts and response contracts
A look back at fetch enabled by default in Node.js 18, with patterns for time limits, status checks and response validation.
The runtime change in 2022
Node.js 18 enabled the global fetch API by default and still described it as experimental. Teams could make some basic HTTP calls without introducing a separate library. The familiar interface does not select timeout, retry or validation policies for a backend. A product catalog should distinguish a missing item from a dependency that failed to respond. Start by writing that contract and then map request outcomes to it.
Separate HTTP responses from network failures
fetch normally fulfills its promise on a 404 or a 500. Evaluate the Response status rather than assuming the request failed at the transport layer. Handle cancellation and network errors separately. A catalog may interpret 404 as no such item, 429 as capacity pressure and 500 as an upstream fault. Converting all failures into an empty catalog hides an important distinction. Log status, dependency and correlation identifiers without dumping response bodies.
Budget time across service boundaries
Use an abort signal to limit an outbound call and account for time already consumed by the enclosing request. Propagate cancellation where supported so abandoned calls do not continue to occupy resources. Retries use time and capacity, so reserve them for suitable operations and bound their attempts. For writes, consider whether the upstream service might have completed the operation before the connection was lost.
Validate the actual response contract
Valid JSON may still have the wrong shape. A service can change the type of a product identifier or omit a currency field. Validate required fields independently of optional values and handle payload size and media type according to capacity. Explicitly decide when partial results are safe. That choice belongs to the user-facing service contract, not to the HTTP request library.
Exercise failure paths in a local test server
Produce 200, 404, 500, invalid JSON and delayed responses without relying on the production dependency. For each test, check the returned result, diagnostic signal and time budget. Measure resource lifetime during a delayed response rather than merely verifying a timeout message. A local fixture also makes it easier to compare behavior after a runtime upgrade. Verify that diagnostics survive cancellation and reach the expected logs.
Comments
No comments yet. Be the first to contribute.
Discussion question from the editor When a catalog dependency responds with 429, would you retry or offer stale data?
Reading “Node.js 18 built-in fetch: Service timeouts and response contracts” raised this question for me: a small reproducible performance comparison would help.
Editor note: Results can vary by scale. Cost, latency and user experience should be compared together.
The learning curve and accessibility also matter for actual users.
A practical case study with load testing or a pilot would help establish the trade-offs.
✎ Write a comment