Integration work gets underestimated more consistently than almost any other part of a software project, usually because “just connect to their API” sounds simpler than it is until you’re actually doing it.
Assuming the documentation is accurate and complete
Third-party API documentation is frequently out of date, incomplete, or silent on edge cases that only show up once you’re actually sending real requests. Budgeting time to test against the real API, not just read about it, is what separates a smooth integration from a stalled one.
No plan for when the external service fails
Every third-party dependency goes down occasionally, or returns unexpected errors, or rate-limits you at an inconvenient moment. An integration with no retry logic, no timeout handling, and no fallback behavior means a hiccup in someone else’s system becomes an outage in yours.
Underestimating authentication complexity
OAuth flows, token refresh, and credential rotation are a common source of integration bugs specifically because they work fine in testing and fail quietly in production weeks later, when a token expires and nobody notices until something stops working.
Not accounting for rate limits in the actual architecture
A design that assumes unlimited calls to a third-party API will eventually hit its limits under real usage, and retrofitting rate-limit handling after launch is far more disruptive than designing for it from the start.
The fix is respecting the unknown
Integration work should be scoped with the assumption that the external system will behave unexpectedly at some point — because eventually, it will. That assumption, built in from the start, is what makes an integration resilient instead of fragile.