Why integrations break, and how to build ones that do not
Integrations break when tokens expire, APIs change, limits are hit or events go missing. The usual causes, and the habits that keep systems in sync.
By Sohail Hussain21 November 20265 min read
Integrations break for a short list of reasons: an access token expires or is revoked, the other system changes or retires its API, a rate limit is hit, a network call times out, an event is delivered twice or not at all, or a record arrives that the other side rejects. None of these can be prevented entirely. A reliable integration assumes they will happen. Every operation is safe to repeat, failures are retried automatically and then shown to a person, and a regular reconciliation compares both systems so nothing goes missing silently.
"Integrations break silently" is the most common complaint we hear when a client comes to our APIs and integrations service, usually about something built quickly a few years earlier. This guide lists the causes and the habits that prevent them.
Why do integrations break?
| Cause | What you see | What prevents it |
|---|---|---|
| Expired or revoked credentials | Every call fails from one moment on | Company-owned integration accounts, automatic token refresh, an alert on the first authentication failure |
| API changes and retirements | Fields disappear, or calls stop working after a vendor's deadline | Pinned API versions, a watch on vendor changelogs, budget for upgrades |
| Rate limits | "Too many requests" errors at busy times; half-finished syncs | Batching, queues, waiting as instructed |
| Timeouts and outages | Intermittent failures with no pattern | Automatic retries with increasing gaps |
| Duplicate or missing events | Double invoices, or orders that never arrive | Operations safe to repeat, plus reconciliation |
| Rejected data | One record fails while the rest go through | Validation, and an error list a person can work through |
| Nobody owns it | Failures noticed weeks later, by a customer | A named owner, monitoring and a one-page description |
Retirements are not hypothetical. Meta's WhatsApp On-Premises API stopped sending messages on October 23, 2025, according to its sunset notice; businesses that had not moved to the Cloud API lost WhatsApp messaging from their systems that day. Every platform you depend on publishes deprecation dates. Someone needs to read them.
How do you make an operation safe to repeat?
Retries are the main defence against failure, and retries are dangerous unless doing something twice has the same effect as doing it once. Engineers call this idempotency. There are four common ways to get it:
- Idempotency keys. Some APIs let you attach a unique key to a request. Stripe's idempotent requests save the result of the first request for a key and return that same result for repeats, so a retried payment request cannot charge a customer twice.
- Upsert by external ID. Store the source system's ID on the target record, and "create or update" rather than "create". A retried order sync updates the invoice it already made.
- A unique constraint. In your own database, make the combination of source and order number unique, so a duplicate insert fails cleanly instead of succeeding quietly.
- An event log. For webhooks, record each event ID and skip ones already processed. Webhooks explained covers this in more detail.
What should happen when a call fails?
First, decide what kind of failure it is. Timeouts, server errors and rate-limit responses are usually temporary, so retry them. Validation errors and "not found" are permanent; retrying a record with a missing tax code a hundred times will not add the tax code.
For temporary failures, wait longer after each attempt (one minute, two, four, eight) with a little randomness so a thousand queued jobs do not all retry at the same second. When the other system answers 429, "too many requests", it may say how long to wait in a Retry-After header, as defined in RFC 6585. Honour it.
After a set number of attempts, stop and move the item to a failed list, then alert a person with enough detail to act: which record, which system, what the error said. If the other system is clearly down, pause the whole sync for a while instead of hammering it.
How do you find out before your customers do?
Log every run. What triggered it, the IDs involved, the result and how long it took, in a form someone can search.
Send alerts to a named person, grouped sensibly. Five hundred identical emails get filtered; one message saying "312 orders failed to sync since 10:40, all with authentication errors" gets fixed.
Watch for silence. Some failures produce no errors at all; the webhook simply stops arriving. Alert when something that always happens has not happened, such as no orders synced by 11 a.m. on a weekday.
Reconcile every day. A scheduled job compares counts and totals in both systems and lists the differences. The cron expression generator helps set the schedule. This is the check that catches everything else on this list.
Give non-developers a status screen: last successful sync, items waiting, items failed. It belongs on the same screen as other operational exceptions, as in how to build an internal dashboard for operations.
Who owns the integration after launch?
The accounts belong to the business. API keys, connector subscriptions and hosting sit in company accounts, with developers added as collaborators. The ownership point in custom software vs off-the-shelf applies to every integration too.
There is one page describing it: what it does, which systems it connects, the field mapping, the schedule, where the logs are, and how to restart it.
Someone watches the vendors. Subscribe to the changelogs and deprecation notices of every API involved, and plan upgrades before the deadline rather than on it.
There is a maintenance budget. Integrations need care the way a website does; website maintenance describes the same idea for sites.
When is a simple integration good enough?
Not every connection needs queues, idempotency keys and reconciliation. A Zapier flow that posts new enquiries to a team chat can fail now and then without harm, as long as the enquiry also reaches the inbox. Build it in an afternoon, switch on the tool's error emails and move on.
Match the effort to the cost of a silent failure. Anything touching money, stock, customer messages or compliance gets the full treatment. Notifications and convenience copies get the simple version. Zapier vs Make vs n8n vs custom code helps decide which platform fits each.
A useful exercise this week: list every integration you run. For each, write down what happens if it stops for a week, who would notice and how. Start fixing the ones where the answer is "a customer".
Was this guide useful?