Five Integration Mistakes That Break Production APIs
The integration bugs we see most often when wiring services together — and the patterns that keep them out of production.
Most integration failures aren't exotic. They're the same handful of mistakes, repeated across teams and stacks. Here are the five we run into most, and how we design around them.
1. Trusting the happy path
The first version of any integration assumes the other service is fast, online, and well-behaved. Production disagrees. Every outbound call needs a timeout, a retry policy with backoff, and a decision about what happens when retries are exhausted.
const res = await fetch(url, { signal: AbortSignal.timeout(5_000) });
if (!res.ok) {
// Don't swallow this. Decide: retry, queue, or fail loudly.
}
A call with no timeout is a latent outage waiting for the upstream to hang.
2. Retrying non-idempotent operations
Retries are great for GET. They're dangerous for "create payment". If you retry
a request that already succeeded but whose response was lost, you double-charge a
customer.
Use idempotency keys for any state-changing call, and make the receiver deduplicate on them.
3. Parsing instead of validating
Treating an upstream JSON response as if your type annotations were guarantees is
how undefined is not a function ends up in your logs. Validate at the boundary —
a schema check turns a vague runtime crash into a clear, attributable error.
4. Leaking the upstream's failure modes
When a downstream dependency returns a 503, your service shouldn't blindly
return a 503 too. Translate failures into your own contract so callers aren't
coupled to an implementation detail they can't see.
5. No visibility when it breaks
If you can't answer "which integration is slow right now?" from a dashboard, you will find out from a customer instead. Log the correlation ID, the latency, and the outcome of every external call.
None of these require clever code. They require treating the network as hostile by default — which, in production, it is.