Your Integration Is Not Done When the Data Flows

For: A COO or operations lead at a 50–200 person company who just signed off on a CRM-to-ERP or similar point-to-point integration, watched it pass QA, and is now three months into production wondering why the business still has data discrepancies, manual reconciliation runs, and a support queue that the integration was supposed to eliminate

An integration is not done when data flows between two systems. It is done when you can answer, without hesitation, what happens to the record that fails — who gets alerted, where the payload lands, who owns fixing it, and how it re-enters the pipeline. If you cannot answer those four questions, you have not shipped an integration. You have shipped a demo that happens to run in production.

This is the mistake I see most often in mid-market operations teams. The CRM-to-ERP project passes QA. Records move. The steering committee signs off. Three months later, finance is running a weekly reconciliation script in Excel, a customer service rep has become the unofficial owner of a shared inbox full of sync failures, and someone is quietly asking whether the integration is actually saving any time at all. The technical work was fine. The error contract was missing.

The happy path is the smallest part of the surface area

When engineers estimate an integration, they estimate the happy path: authenticate, map fields, transform, send, confirm. That work is real, but it is maybe 30% of what determines whether the integration survives contact with production. The other 70% is the failure taxonomy — every way a record can go sideways and what the system should do about it.

A partial list of what production actually throws at you:

• A required field arrives null because a rep skipped it in Salesforce
• A record arrives out of order — the update lands before the create
• The downstream system rejects the payload for a validation rule that wasn't in the docs
• A vendor pushes a schema change on a Tuesday with no changelog
• An API rate-limits you at month-end when volume triples
• A timeout leaves you unsure whether the write succeeded
• A duplicate arrives because your retry logic doesn't know the first attempt actually worked

Each of these has a correct handling behavior. Most integrations have no defined handling behavior for any of them. The default becomes: log the error somewhere, keep going, and hope someone downstream catches it. Someone downstream is your operations team. They catch it by noticing the P&L is wrong.

What an error contract actually looks like

An error contract is a written agreement — before the integration ships — about how the system behaves when things go wrong. It is not a Confluence page nobody reads. It is a set of decisions that get encoded in the integration itself and the runbook around it. At minimum, it answers:

1. Classification. Is this error transient (retry), permanent (dead-letter), or ambiguous (human review)? Every possible error code from every endpoint needs a bucket.
2. Ownership. Who owns the dead-letter queue? Not "the team" — a named role. When a record lands there, whose Monday morning does it show up on?
3. Alerting thresholds. Does one failed record page someone? A hundred? A percentage of daily volume? What is normal noise and what is a real incident?
4. Replay. How does a fixed record get back into the flow? Is there a UI, a CLI, a ticket someone files with engineering? If replay requires an engineer, you have already lost.
5. Idempotency. If you retry a payload, will the downstream system create a duplicate or recognize it as the same operation? This is not optional.
6. Schema drift. When the vendor adds a field or changes a type, does your pipeline fail loudly, silently drop it, or best-effort adapt? Pick one on purpose.

You will notice none of this is glamorous. It is the plumbing under the plumbing. It is also the difference between an integration that reduces headcount pressure and one that adds a permanent, invisible tax to your operations team.

Three ways this fails in the wild

Example one: the null field that ate reconciliation. A B2B SaaS company syncs closed-won opportunities from Salesforce to NetSuite. In staging, every test record has a billing country. In production, about 4% don't, because reps close deals without filling out the account address. The integration silently defaults the country to US. Six months later, VAT reporting for European customers is wrong, and finance spends two weeks unwinding it. The engineering fix takes an hour. The trust rebuild takes a quarter.

Example two: the retry storm. An e-commerce operator integrates their order system with a fulfillment provider. The fulfillment API returns 503s for a few minutes during a deploy. The integration retries aggressively, without idempotency keys. When the fulfillment API comes back, it processes every retry as a new order. The warehouse ships duplicates. Customers get charged twice. The integration was working perfectly, by its own definition.

Example three: the schema change nobody saw. A HubSpot-to-data-warehouse pipeline runs cleanly for a year. HubSpot renames a property. The pipeline keeps running, pulling nulls into a column the marketing team uses for attribution. Nobody notices until Q3 planning, when someone asks why paid social has stopped converting. It hasn't. The reporting has.

In all three cases, the integration "worked." Data flowed. QA would have signed off on all of them the day they launched.

The strongest counter-argument

Here is the honest pushback: you can spend forever engineering for edge cases that never happen, and most integrations at a 50-200 person company do not need airline-grade reliability. That is fair. The point is not to build every integration like it is running a nuclear reactor. The point is to make the decision consciously.

A reasonable middle path: for any integration touching money, inventory, customer identity, or regulated data, invest in a real error contract before go-live. For internal marketing tool syncs where the worst case is a manually re-imported CSV, a lightweight logging-and-alerting setup is probably enough. What you cannot do is treat every integration as low-stakes by default, because that is how the CRM-to-ERP sync — which touches revenue recognition — ends up with the same error handling as the Slack notification bot.

The other reasonable pushback: iPaaS platforms like Workato, Boomi, and MuleSoft handle a lot of this for you. Partially true. They give you the primitives — dead-letter queues, retries, monitoring dashboards. They do not decide who owns the queue, what your alert threshold is, or how a fixed record replays. That is still your work. The platform is a tool, not a contract.

What to do differently on Monday

If you are the operations lead reading this and you have an integration in production that feels wrong, here is a short diagnostic:

• Ask engineering to show you the dead-letter queue. If they don't have one, that is your finding.
• Ask who owns it. If the answer is "we look at it when there's a problem," that is your finding.
• Ask what the alert threshold is. If there is no alerting, that is your finding.
• Ask how a failed record gets replayed. If it requires an engineer to run a script, that is your finding.
• Ask what happens if the upstream vendor changes a field name tomorrow. If the answer is "we'd probably find out eventually," that is your finding.

If you are scoping a new integration, do not accept "data flows in staging" as the definition of done. Write the error contract into the requirements before a line of integration code gets written. Make dead-letter handling, idempotency, alerting, replay, and schema-drift behavior explicit deliverables. Assign a business owner — not just an engineering owner — for the queue.

Integrations fail operationally long before they fail technically. The teams that understand this ship fewer integrations, but the ones they ship actually reduce work instead of relocating it. Everyone else ends up with a support queue and a reconciliation spreadsheet, and a nagging sense that the platform investment did not pay off. It did. The integration just wasn't done.

For teams working through this on live systems — particularly around legacy modernization and cross-system data flow — the biggest single lever is often not more integration engineering. It is defining the error contract for the integrations you already have.

Frequently Asked Questions

What is an error contract in a software integration?

An error contract is a written, agreed-upon definition of how an integration behaves when things go wrong: which errors get retried, which get dead-lettered, who is alerted, who owns fixing failed records, and how those records get back into the flow. It is decided before the integration ships, not after the first production incident.

Why do integrations pass QA but fail in production?

QA typically covers the happy path — well-formed data moving between systems under expected conditions. Production introduces null fields, out-of-order events, rate limits, timeouts, vendor schema changes, and edge cases that no test suite fully captures. Without explicit handling for these, the integration technically works while the business absorbs the cost of manual cleanup.

What are the most common enterprise integration pitfalls?

The top ones are: no dead-letter queue, no defined owner for failed records, no idempotency on retries, no alerting thresholds distinguishing noise from incidents, and no monitoring for upstream schema drift. Any one of these is enough to turn a working integration into a hidden operational tax.

Do iPaaS platforms like Workato or MuleSoft solve this?

They provide the technical primitives — retries, dead-letter queues, monitoring — but they do not decide your ownership model, alert thresholds, or replay process. Those are business decisions the platform cannot make for you. The tooling helps; it does not replace the contract.

How do we assess whether our existing integrations have this problem?

Ask five questions: Where is the dead-letter queue? Who owns it by name? What triggers an alert? How does a fixed record get replayed? What happens on a vendor schema change? If any answer is vague, you have a gap. For a structured review of an existing integration estate, contact CodeNicely for a personalized assessment.