Consuming Third-Party APIs Without Becoming Their Outage
Key takeaway
Every external API call needs an explicit timeout, a retry policy with backoff and jitter, and a defined behaviour when it fails. Without those three, a slow third party doesn't degrade your application — it exhausts your connection pool and takes the whole thing down.
Integrating an external API is easy to make work and hard to make reliable. The difference shows up the first time the provider has a bad afternoon and your application has one too.
The four defaults every client needs
- An explicit connect and read timeout. Library defaults are frequently infinite, and an infinite timeout is how one slow dependency consumes every worker you have.
- Retries with exponential backoff and jitter — and only on idempotent operations or with an idempotency key. Naive immediate retries turn a provider's blip into a stampede.
- A circuit breaker: after repeated failures, stop calling for a while and fail fast. This protects both you and them.
- A defined fallback — cached data, a queued action, or an honest error. Decide it deliberately rather than letting an exception choose.
Rate limits are a design input, not an edge case
- Read the limits before designing the integration; they often rule out the obvious approach.
- Respect Retry-After when it's returned rather than guessing.
- Batch where the API supports it, and cache reference data that barely changes.
- Throttle on your side, so a background job can't consume the quota your live checkout needs.
Handling money and side effects
For anything that charges, ships, or sends, use the provider's idempotency key so a retry can't double-charge. Record your own reference before the call, not after, so that a timeout leaves you able to reconcile rather than guessing whether it happened. Ambiguous outcomes are the normal case in distributed systems, and the reconciliation job is not optional.
Observability and change
- Track latency percentiles and error rates per provider — you need evidence when you open a support ticket.
- Alert on error rate, not on single failures.
- Log request ids returned by the provider; they're the first thing their support will ask for.
- Subscribe to their status page and changelog, and pin API versions so an upstream change is a decision rather than a surprise.