We integrated a payment provider. Their status page was green, their /health endpoint returned 200, and our checkout was failing for 8% of users. The support ticket war that followed taught me more about integration than any happy-path tutorial ever did.
The problem: their health check only proved their load balancer was answering. It said nothing about whether the actual payment path worked. Their auth service was intermittently timing out, but the health endpoint didn't touch auth, so it stayed cheerfully green while real transactions died. We were trusting a signal that measured the wrong thing.
That's the core lesson of integration: someone else's "up" is not your "working." The only health that matters is whether the operations you actually depend on succeed. So I stopped trusting their health endpoint and started measuring the real thing — the success rate of our actual payment calls, sliced by their error codes. That number is the truth. A vendor status page is marketing.
While I was in there, I fixed our side too, because we were just as guilty of naive assumptions. We had no timeout on the call, so when their auth hung, our threads hung with it, and one slow dependency was quietly eating our own capacity. We added an aggressive timeout, a retry with backoff and jitter for the transient timeouts only — never retry a decline, you'll double-charge someone — and a circuit breaker so that when they were genuinely down we failed fast and showed users an honest "try again in a minute" instead of a thirty-second spinner.
The part I'm proudest of: we made the integration observable from our side. Every call logs the upstream latency and status code, and we alert on our success rate for that dependency, not theirs. When it degrades now, we know before their status page does, and we can tell support exactly which error codes we're seeing and when.
Integrate with other people's systems as if they will fail, because they will, and they won't tell you first. Timeouts, retries with jitter, circuit breakers, and your own measurement of the thing you actually need. Their green light is their problem. Your users are yours.
– Sergey Shinder
Top comments (0)