Lorixen.
EN

Set timeouts on third-party API calls before they take you down

Short answer: Every time your website or app calls another company's service, such as a payment provider, shipping-rate API, stock feed, address lookup or email service, it should give up after a sensible time. Many HTTP libraries wait indefinitely by default, so one slow supplier can tie up your server's workers until your whole site stops responding. Set a short connect timeout and a read timeout on every outbound call, decide what the customer sees when a call times out, and log timeouts so you can see which supplier is struggling.

Why missing timeouts take sites down

A web server can only handle so many requests at once. If each checkout calls a shipping-rate API and that API stops responding, each request waits. Without a timeout, it may wait for minutes. New customers arrive, more requests wait, and soon every worker is stuck waiting for the same slow supplier. To customers it looks like your whole site is down, even though your own code and database are fine.

The Python Requests library's documentation is blunt about this: most requests to external servers should have a timeout attached, by default requests do not time out unless a timeout is set explicitly, and without one your code may hang for minutes or more. Many other HTTP clients behave similarly or have very long defaults.

Two kinds of timeout

The Requests documentation distinguishes:

  • Connect timeout: how long to wait to establish a connection to the remote server. It suggests setting it slightly larger than a multiple of 3 seconds, the default TCP packet retransmission window.
  • Read timeout: once connected and the request is sent, how long to wait for the server to send a response, more precisely the time between bytes received.

It also notes that neither is a wall-clock limit: a request can take longer overall than either number. If you need an overall deadline, add one separately.

In browser and modern JavaScript code, MDN documents AbortSignal.timeout(), which returns a signal that automatically aborts after a set number of milliseconds and rejects with a TimeoutError. MDN's example passes it to fetch() so a request gives up after 5 seconds.

Choosing values

There's no universal number, but a practical approach:

  • Connect: a few seconds. If a server can't accept a connection quickly, it's unlikely to help to wait.
  • Read: based on the supplier's normal response time plus a margin. If a rates API normally answers in under a second, waiting 30 seconds helps nobody.
  • Shorter for page loads, longer for background jobs. A customer waiting on a page needs a quick answer; a nightly import can afford to wait longer.

Measure real response times from your logs before choosing, and revisit after a supplier changes.

Decide what happens on timeout

A timeout is only useful if the app does something sensible next:

Call Reasonable fallback
Shipping rates at checkout Show a standard flat rate or "calculated after order" message
Address lookup Let the customer type the address manually
Stock check Show cached stock and confirm later
Payment Show a clear error and don't retry blindly; check the payment status first
Sending an email Put it on a queue and retry in the background
Analytics or tracking Ignore the failure

Payments deserve special care: a timeout doesn't mean the payment failed. Check the provider's status for that payment before trying again, and use idempotency keys where the provider supports them.

Move slow calls out of the request

If a call is slow by nature, don't make the customer wait for it. Queue it as a background job and update the page or send an email when it's done.

Log and monitor timeouts

  • Log each timeout with the supplier, endpoint and duration.
  • Alert when timeouts for one supplier spike.
  • Track response times so you notice a supplier slowing before it fails.

Where to look in your code

Search your codebase for every HTTP client call and confirm a timeout is set, including:

  • direct HTTP calls;
  • SDKs from payment, shipping and email providers, which often have their own timeout settings;
  • plugins and extensions on platforms like WordPress or shop systems, which may call external services on every page load;
  • server-side rendering or build steps that fetch data.

A shared helper that always applies timeouts makes this easier to enforce.

Test what happens when a supplier is slow

Don't wait for a real outage to find out. In a staging environment, point one integration at a test endpoint that deliberately responds slowly or not at all, then load the affected page. Check that the page still responds within a few seconds, that the fallback appears, that the error is logged and that other pages are unaffected. Repeat for each important supplier. Some teams keep a simple "slow supplier" switch in staging so this test can be run before every major release.

Ask suppliers about their limits

Supplier documentation often states expected response times, rate limits and status page addresses. Subscribe to their status updates, so when your timeout alerts fire you can quickly see whether the problem is theirs or yours, and tell customers accurately what's happening.

An illustrative example

A hypothetical Chicago gift shop's site froze every afternoon for a few minutes. Logs showed the checkout called a shipping-rate API with no timeout, and that API slowed down at busy times. All web workers ended up waiting. The developer set a 3-second connect timeout and 5-second read timeout, showed a flat-rate fallback when rates weren't available, and added an alert for shipping-API timeouts. The freezes stopped, and the shop could see exactly when the supplier struggled.

FAQ

Won't timeouts cause more errors?

They turn a site-wide outage into a contained, handled error on one feature.

Should I retry after a timeout?

Sometimes, with a limit and a delay, and never blindly for payments.

Does a CDN protect me?

No. CDNs handle incoming traffic, not your server's outgoing calls.

What about database queries?

They need timeouts too, configured separately.

If your site slows or freezes when a supplier's service is slow, tell us which services you connect to.

Sources

WhatsAppBook a call