Common API Integration Challenges
Most integration problems fall into a handful of repeat categories: the provider changes its schema or API version, authentication expires without warning, rate limits or downtime disrupt the connection, or the two systems disagree on identifiers for the same record. Designing for retries, idempotency and clear ownership catches most of these before they cause damage.
Schema, Authentication and Version Changes
Imagine a freight brokerage whose booking system integrates with a transport aggregator's API to fetch live rates and confirm bookings. Six months after launch, bookings start silently failing — the aggregator released a new API version and deprecated a field the integration depended on, without the brokerage's team noticing the release notes.
Authentication tokens expiring is a related, equally common cause: a token or key that was valid at launch has a renewal or rotation requirement that nobody scheduled for, and the integration fails all at once on the day it lapses rather than degrading gradually.
Rate Limits, Latency and Availability
Every third-party API enforces some limit on how many requests it will accept in a given period, and an integration that worked fine at low volume can start failing once the business grows past that limit — not because anything changed on either side, but because usage crossed a threshold nobody had checked in the provider's documentation.
Latency and outright downtime on the provider's side are outside the business's control entirely, but the integration's behaviour when they happen is not — a slow or unavailable provider should degrade the business's own system gracefully (queueing the request, showing a clear status) rather than causing an unrelated part of the application to fail or hang.
Inconsistent Identifiers and Data Conflicts
Two systems rarely agree on how to identify the same real-world thing without deliberate mapping — a customer, a shipment, an order — and when that mapping is incomplete or inconsistent, records can silently duplicate or update the wrong entity. This is often the least visible failure mode, because nothing errors out; the data is simply wrong.
Conflicting updates — both systems changing the same field independently — are a variation of the same root problem, and without a clear rule for which side wins, the two systems can end up in a quiet, ongoing disagreement that only surfaces when someone happens to compare them directly.
Design for Retries, Idempotency and Observability
A retry after a failed or uncertain request is necessary, but a retry without idempotency — a way to guarantee the same request processed twice has the same effect as processing it once — is how duplicate bookings, duplicate invoices and duplicate charges happen. Building a unique reference into every request that the receiving system can use to detect a repeat is the standard fix.
Observability — logging, alerting, and a dashboard showing the integration's recent success and failure rate — is what turns a silent failure into one that's noticed within minutes instead of weeks. Without it, the freight brokerage's schema-change failure above might only have been discovered when a customer called asking why their booking never confirmed.
Assign Maintenance Ownership and Incident Playbooks
An integration needs a named owner after launch, not just during the build — someone whose job includes checking the exception queue, reading provider release notes, and being the first call when something breaks. Without that, responsibility for a shared connection tends to fall to whoever happens to notice the problem, which is unreliable by design.
A short incident playbook — what to check first, who to contact at the provider, how to tell customers if the failure is visible to them — turns a stressful, ad-hoc scramble into a known procedure the next time something goes wrong, and something eventually will.
Integration failure modes table
A table listing common failure modes — schema change, expired auth, rate limit breach, provider downtime, identifier mismatch, duplicate processing — each with its typical warning sign, the design choice that prevents it, and who should own watching for it.
Frequently asked questions
Why do previously working integrations fail?
Almost always because something changed on one side without the other side being told — a provider's API version, an expiring credential, or a volume that finally crossed a rate limit. The integration itself didn't get worse; the conditions around it changed.
How can failures be detected early?
Active monitoring — a dashboard or alert on failed requests, rather than waiting for a customer or colleague to notice something's wrong — plus a habit of checking provider release notes and status pages before they cause an outage rather than after.
Have a specific situation to work through?
This article covers the general case. Tell us what you're actually dealing with and we'll respond directly.