Most Integration Failures Aren't Technical — They're Assumption Mismatches

Two systems that both work fine on their own break when connected — not because the code is wrong, but because each team built to a different unstated assumption about how the other side would behave. That's the actual lesson from every integration project: the failure is rarely technical incompatibility, it's a mismatch nobody wrote down.

The Contract Nobody Signed

Every integration has an implicit contract: what fields are guaranteed to be present, what happens on a malformed request, how errors get communicated, what the rate limit actually is under load. Teams build against their assumptions about that contract instead of an explicit spec, and the two sets of assumptions only get compared for the first time when something breaks in production. Write the contract down before either side writes code — even a one-page doc beats discovering the mismatch live.

Design for the Retry, Not Just the Request

Networks fail, and whoever's calling your system will retry — with or without your permission. If a retried "create order" call creates a second order, that's not the caller's bug, it's yours. Idempotency keys, or at minimum a way to detect "I've already processed this exact request," are what make retries safe instead of dangerous. Assume every request will eventually be sent twice.

Whose Alert Fires When Data Stops Flowing?

Integrations fail silently more often than loudly — a feed stops updating, a webhook stops firing, and nobody notices for three days because both sides assumed the other side was watching. Before launch, name the specific person or system responsible for noticing "this stopped working," on both sides of the connection. If the answer is "nobody, we'll notice when a customer complains," that's the actual monitoring plan, whether anyone admits it or not.

The Other System Will Change Without Telling You

Whatever you're integrating with today will eventually change its response format, deprecate a field, or shift its rate limits — and the changelog, if it exists, may or may not reach you. Version your own side defensively: validate what you receive instead of trusting it blindly, and fail loudly on unexpected shapes instead of silently passing through bad data. The integration that survives years is the one that assumed the other end would eventually move, not the one that assumed it wouldn't.

Conclusion

Communication, planning, and testing matter, but they're not the lesson — they're the mechanism for catching mismatched assumptions before they reach production instead of after. The teams that get good at integration aren't the ones with the cleverest code; they're the ones who got disciplined about writing down what each side actually assumes.

Tyrone Showers