In this guide 6 sections
Integrations break for repeat reasons. Providers retire a field or version, credentials lapse without a reminder, rate limits throttle growing traffic, and two systems name one customer record differently. Retries with idempotency keys, a monitored failure queue and a named owner catch most of these long before a customer phones to complain.
Schema, authentication and version changes
Consider a freight brokerage that fetches live rates and confirms bookings through a transport aggregator’s API, a connection that has run quietly for six months. Then bookings stop confirming. The aggregator shipped a new version, retired a field the booking form relied on, and announced it only in release notes that sat unread in a shared mailbox.
Expired credentials break things too. An API key or OAuth token issued at launch carries a renewal date, and without a calendar entry the connection dies in one afternoon instead of fading. Diarise every expiry date. Subscribe a named mailbox to the provider’s changelog and deprecation notices, then read each one against the fields your integration actually sends and receives.
Rate limits, latency and availability
Every third-party API caps requests per minute or per day, and a connection that worked at low volume starts returning too-many-requests errors once order counts grow past that cap. Nothing changed on either side. Volume crossed a limit printed in the provider’s documentation that nobody checked, so the first symptom is a wave of rejected requests in the busiest hour.
Provider outages are not yours to prevent. How your own system behaves during one is yours to design: queue the booking request, show the customer a pending status, and retry with growing gaps between attempts. A slow provider should never freeze checkout. Set a timeout on every outbound call so one stalled response cannot hold a web worker, a database connection and a customer’s patience hostage for minutes.
Inconsistent identifiers and data conflicts
Two systems rarely agree on how to identify the same customer, shipment or order unless somebody builds and maintains the mapping between their identifiers. Mapping gaps hurt quietly. A booking arrives under a slightly different consignee name, the integration creates a second record, and finance invoices two customers who are actually one. No error appears anywhere. The data is simply wrong.
Conflicting edits share the root cause. When both systems may change a delivery address, write down which side wins, and add a timestamp comparison for cases the rule cannot settle. Without that rule, the two records drift apart and the gap surfaces only when somebody compares them side by side during an audit or a complaint.
Retries, idempotency and observability
Retrying a failed request is necessary. Retrying without idempotency is how duplicate bookings, invoices and card charges get created when a timeout hides the fact that the first attempt actually succeeded. Idempotent means safe to repeat. Put a unique reference in every outgoing request, store it with the result, and have the receiving system return the original outcome when it sees that reference again.
Observability makes silent failures loud. Log every request with its reference and status, alert when failures rise above their normal baseline, and keep a dashboard of recent results that someone opens each morning. The brokerage’s schema change would have shown up within minutes instead of surfacing when a customer rang asking why a booking never confirmed.
Maintenance ownership and incident playbooks
Every integration needs a named owner. That owner reads the provider’s release notes, clears the exception queue daily, and takes the first call when a sync stops, leaving no room for guesswork. Responsibility for a shared connection otherwise lands on whoever happens to spot the problem, and that is unreliable by design.
Write a one-page playbook. It lists what to check first, which contact at the provider answers urgent tickets, how to pause the queue, and what to tell customers whose bookings are stuck. Something will break eventually.
Integration failure modes table
One row per failure mode in a table: schema change, expired credential, rate limit breach, provider outage, identifier mismatch and duplicate processing. Each row names the warning sign, the design choice that prevents it, the person who watches for it, and when it was last tested.
Open a blank worksheet to printQuestions owners ask
Why do previously working integrations fail?
Usually one side changed and the other was never told: a provider retired an API version, a credential reached its renewal date, or volume crossed a rate limit. The integration itself did not get worse. The conditions around it moved.
How can failures be detected early?
Alert on the failure rate and on silence, meaning no successful sync for longer than usual, because a dead connection produces no errors to count. Read the changelog too.
What is an idempotency key?
It is a unique reference sent with each request, such as the booking number, that lets the receiver spot a repeat and return the first result. Retries then become safe.