Why most integrations fail (and how to avoid it)
Most integration projects don't fail because of bad code. They fail because of unclear ownership, undocumented assumptions, and a lack of error handling strategy from day one.
The myth of the technical problem
When an integration breaks in production, the post-mortem almost always surfaces a technical root cause - a missing retry, an unexpected null, a schema mismatch. But if you dig one level deeper, you usually find a human cause: nobody owned the contract between the two systems, the error case was never discussed, or the team assumed the other side would handle it.
Technical problems are easy to fix. Organisational problems wearing technical clothing are much harder.
Unclear ownership
The most common failure pattern we see: two teams, two systems, one integration - and nobody who is definitively responsible for it. When something breaks at 2am, both teams assume the other is handling it. The integration lives in a grey zone between codebases, between on-call rotations, between backlogs.
The fix is deliberately boring: assign an owner before the first line of code is written. The owner doesn't need to build it, but they are accountable for it working. That changes how the integration is designed, tested, and monitored.
Undocumented assumptions
Every integration is built on assumptions about the other system - what fields will always be present, what the maximum payload size is, how the remote API behaves under load. These assumptions are usually correct at build time. They become bugs six months later when the remote system is updated and nobody thought to tell you.
We treat every assumption as a risk. We document them explicitly, validate them at runtime where possible, and build alerts that fire when they are violated. Assumptions that live only in a developer's head are liabilities.
No error handling strategy
Most integrations are designed for the happy path. Error handling is bolted on afterward, inconsistently, and usually only after a production incident has made it unavoidable. The result is integrations that work perfectly in demos and unpredictably in production.
A proper error handling strategy answers three questions before you start building: What happens when the remote system is unavailable? What happens when it returns unexpected data? What happens when our side fails partway through a transaction? If you can't answer these questions at design time, you are not ready to build.
What to do instead
Assign an owner. Document every assumption. Design for failure before you design for success. Instrument everything - not just error rates, but latency, payload sizes, and schema drift.
None of this is glamorous. But it is the difference between integrations that quietly run for years and integrations that become technical debt within months.