Common Integration Mistakes and How to Avoid Them

In twenty-two years of connecting ERP, EAM, CAFM and a long tail of line-of-business systems, I have seen very few integrations fail because the technology could not do the job. The tools are mature. REST, queues, event streams and integration platforms all work as advertised. What fails is judgement: decisions made early, under schedule pressure, that look harmless in a demo and become expensive in production. The good news in that observation is that if the mistakes are predictable, they are also preventable. This guide is a walk through the ones I see most, each paired with the discipline that avoids it. If you want the wider conceptual map first, start with the pillar on enterprise system integration explained, then come back here for the sharp edges.

The message up front: integration is not a coding problem, it is a contracts, data and operations problem. The teams that get it right are not the ones with the cleverest code. They are the ones who agreed a canonical data model, planned for failure before it happened, and could see what was flowing on any given day. Everything below is a variation on those three habits.

1. Why integrations fail (it is rarely the technology)

When a project post-mortem lands on my desk, the stated cause is usually technical: a timeout, a malformed payload, a duplicate record, a security incident. But trace each one back and the root cause sits upstream of the code. The timeout was never handled because nobody designed for the downstream system being slow. The malformed payload got through because there was no agreed contract to validate against. The duplicates appeared because the interface was not idempotent and a retry ran twice. The security incident happened because credentials were an afterthought bolted on at go-live. In every case the technology behaved exactly as instructed. The instructions were the problem.

There is a common shape to how this happens. Integration work is estimated as if it were a straight data-copy exercise, a pipe between two boxes. The happy path is built quickly, it demos beautifully, and everyone declares victory. Then production arrives, with its network blips, its partial outages, its unexpected data, its volume spikes and its malicious actors, and the interface that only ever knew the happy path starts to buckle. The real work of integration, the eighty percent that never appears in the demo, is everything that happens when the happy path does not hold. Skip that work and you have not built an integration, you have built a demo that happens to run in production.

The rest of this article is a catalogue of the specific ways that eighty percent gets skipped, and what to do instead. None of them require exotic technology. They require deciding, early and deliberately, to design for reality rather than for the demo.

2. No canonical model and tight coupling

The first and most structural mistake is letting every system talk to every other system in that other system's native language. It feels efficient at the start. You need the ERP to send an order to the warehouse system, so you write code that reads the ERP's order shape and writes the warehouse's order shape directly. It works. Then finance needs the same order, so you write a second mapping. Then the CAFM system needs it, a third mapping. Each new consumer means another point-to-point translation that knows the intimate internal shape of the source. You have coupled every system tightly to every other, and now a field rename in the ERP breaks four interfaces you had forgotten existed.

The discipline that prevents this is a canonical data model: an agreed, system-neutral representation of your core business objects. A customer, an order, an asset, an invoice, defined once in a shape that belongs to no single application. Each system maps once, into and out of the canonical shape, and never needs to know the internal structure of any other system. When the ERP renames a field, you fix one mapping, the ERP-to-canonical one, and every consumer is insulated. This is the difference the diagram below is trying to show: the same set of systems, first coupled directly to each other, then decoupled through a shared model.

The left side is what grows organically when nobody stops it: connections multiply roughly with the square of the number of systems, and each one is a maintenance liability. The right side costs a little more discipline up front, because you have to agree what an order or an asset actually means across the business, but it grows linearly and stays comprehensible. For the fuller treatment of how to lay this out, including where the canonical model lives and how it relates to the transport, see how to design integration architecture.

3. Ignoring error handling and retries

The single most common reason a working integration turns into a support nightmare is that it was built for the case where nothing goes wrong. In a distributed system, something is always going wrong somewhere: a network hiccup, a database lock, a downstream service restarting, a rate limit hit, a message that arrives before the record it references. If your interface treats every one of these as a fatal, unhandled exception, then every transient blip becomes a lost message and a manual clean-up job.

Good error handling starts by distinguishing the two kinds of failure, because they need opposite responses. Transient failures, a timeout or a temporary unavailability, will probably succeed if you simply try again in a moment. Permanent failures, a validation error or a reference to something that does not exist, will never succeed no matter how many times you retry, and retrying them just wastes cycles and floods logs. The mistake is to treat both the same way: either giving up on transient errors that a retry would have fixed, or hammering a permanent error in an infinite retry loop.

The mature pattern is retry with exponential backoff for transient failures, a bounded number of attempts, and then a dead-letter queue for anything that still will not go through. The dead-letter queue is the part teams skip and later regret. It is the holding pen where failed messages wait, intact and inspectable, instead of vanishing. Without it, a failure means data silently lost. With it, a failure means a message parked safely for a human to look at, fix and replay. I treat a dead-letter queue and an alert on it as non-negotiable on any interface that matters. This whole topic deserves its own study, which is why I wrote integration error handling best practices as a dedicated companion piece.

4. No idempotency

Idempotency is the property that processing the same message twice produces the same result as processing it once. It sounds academic until you realise that retries, the very thing that makes an integration resilient, guarantee you will eventually process some messages more than once. A message is sent, the downstream system processes it successfully, but the acknowledgement is lost on the way back. The sender, having heard nothing, retries. Now the same order has been created twice, the same payment posted twice, the same asset registered twice. The retry mechanism that was supposed to add reliability has instead corrupted your data.

This is not an edge case. In any at-least-once delivery system, and almost every practical messaging system is at-least-once rather than exactly-once, duplicates are not a possibility to guard against, they are a certainty to design for. The mistake is assuming each message arrives precisely once and building the consumer accordingly. The fix is to make the consumer safe against repeats by giving each message a stable, unique identifier and having the receiver record which identifiers it has already processed. When a duplicate arrives, the receiver recognises the identifier, acknowledges it, and does nothing else. Alternatively, design the operation itself to be naturally idempotent, an upsert keyed on business identity rather than a blind insert, so that applying it twice lands in the same state.

The trap to watch for: idempotency and error handling are joined at the hip. The moment you add retries to make an interface resilient, you have created the conditions for duplicates. Adding retries without adding idempotency does not make the integration safer, it makes it dangerous in a new way. If you take one pairing from this article, take this one: never ship a retry without an idempotency key behind it.

5. Point-to-point spaghetti

This is the operational cousin of the canonical-model mistake, and it deserves its own section because of how it degrades over time. Point-to-point spaghetti is what you get when each new integration requirement is met by wiring the two systems directly together, with no shared infrastructure, no common patterns and no central visibility. Individually each connection is reasonable. Collectively they form a web that no single person understands, where changing anything risks breaking something nobody can predict.

The symptoms are familiar to anyone who has inherited an older estate. Nobody can produce an accurate diagram of what talks to what. A field change requires a nervous archaeology exercise to find every consumer. Interfaces are written in five different styles by five different contractors, each with its own error handling, its own logging, its own credentials management, so operating them is a per-interface guessing game. When one system goes down for maintenance, the blast radius is unknown until things start failing. The estate becomes a set of load-bearing walls that everyone is afraid to touch, which is exactly the state where organisations stop being able to change their systems at all.

The cure is not necessarily a heavyweight enterprise service bus. It is consolidation onto shared patterns and a shared piece of connective tissue, whether that is a modern integration platform, a message broker, or an event backbone. What matters is that interfaces stop being bespoke one-offs and start being instances of a small number of well-understood patterns, routed through infrastructure that gives you one place to see traffic, apply security and manage change. The point is decoupling and visibility, not any particular product. Once systems talk through a layer rather than directly to each other, you can evolve, replace or take down any one of them without a domino effect through the rest.

6. Poor or no monitoring

Here is a question I ask on every integration review: if an interface stopped working right now, how would you find out? Uncomfortably often the honest answer is that a user in a downstream department would eventually notice that data was missing and raise a ticket, and someone would trace it back. That is not monitoring. That is your customers doing your alerting for you, hours or days after the fact, by which point the backlog is large and the trust is spent.

An integration with no monitoring is a black box that you have to trust blindly and cannot diagnose when it misbehaves. The mistake is treating monitoring as an optional extra to add later, when in reality it is part of the interface. At minimum every integration should emit the basics: is it running, how many messages has it processed, how many have failed, how long is the queue, how old is the oldest unprocessed item, and are there messages sitting in the dead-letter queue. Those handful of signals, surfaced on a dashboard and wired to an alert, turn a black box into an observable system. You find out about problems from your own instruments, while the backlog is still small, instead of from an angry email once it is large.

Alongside metrics you need traceability. When a specific record did not arrive, you should be able to follow that one message through the pipeline and see where it stopped. That means correlation identifiers carried end to end and enough structured logging to reconstruct the journey. Monitoring tells you something is wrong; traceability tells you what and where. Skimping on either turns every production incident into a multi-hour investigation that a few lines of instrumentation would have made a five-minute lookup.

7. Security as an afterthought

Security bolted on at the end is one of the most expensive mistakes in this catalogue, because retrofitting it means unpicking decisions baked into the interface from the start. The classic failure pattern is an integration built and tested in a comfortable internal environment with authentication switched off or a shared static password, on the assumption that it can be secured just before go-live. Then go-live arrives, the deadline is tight, and the interface ships with credentials in plain text in a config file, no encryption in transit on some hop, and permissions far broader than the integration actually needs, because narrowing them now would mean re-testing everything.

Integrations are a uniquely attractive target precisely because they are trusted, privileged connections that move real business data between systems, often with elevated rights. A compromised integration credential is frequently a skeleton key. The disciplines are not exotic: encrypt data in transit and at rest, authenticate every call with properly managed secrets rather than passwords in source control, and apply least privilege so each interface can touch only the specific data and operations it needs and nothing more. The thing that makes these hard is not the technology, it is that they must be designed in from the first line rather than sprinkled on at the end. An interface built with least privilege and managed secrets from day one is straightforward. The same interface secured retroactively under deadline pressure is a painful, error-prone rework. I go into the full checklist in integration security best practices.

8. No versioning or contracts

The last structural mistake is treating an interface as a private arrangement that either side can change at will, rather than as a contract that consumers depend on. An integration contract is the agreed shape of the data and the behaviour of the interface: what fields exist, what they mean, which are mandatory, what the operations do. Consumers build against that contract. The moment a producer changes it without warning, by renaming a field, removing one, changing a type or altering a meaning, every consumer that relied on the old shape breaks, usually silently and usually in production.

The mistake takes two forms. The first is having no explicit contract at all, so the interface's shape is whatever the code happens to emit today, undocumented and unguaranteed, which makes every producer change a game of chance. The second is having a contract but no versioning strategy, so there is no safe way to evolve it. Real systems must change, so the goal is not a frozen contract, it is a governed one. That means an explicit, documented contract, additive changes wherever possible so that adding a field never breaks an existing consumer, and genuine versioning for breaking changes so old and new consumers can coexist while everyone migrates on a schedule rather than being broken overnight. Platforms with well-defined public interfaces make this concrete: for example, working against the Business Central APIs and integrations means building to versioned, published contracts rather than reaching into internal tables, which is exactly the discipline you want to impose on your own interfaces too.

9. The mistakes summarized

Pulled together, the pattern is clear: each mistake has a recognisable symptom in production and a specific design habit that prevents it. The table below is the one-page version I hand to teams at the start of an integration project, so the fixes are decided up front rather than discovered under pressure.

Read the middle column and the right column together and a theme emerges. Every symptom is something that shows up only in production, under real conditions, which is exactly why these mistakes survive the demo and the test environment. And every fix is a decision made early, cheaply, before a line of the happy path is written. That timing is the whole game. These are not expensive things to do. They are only expensive to do late.

10. References

The recommendations above are drawn from hands-on delivery across ERP, EAM and CAFM integration work rather than from any single source, but they align with well-established industry thinking. For readers who want to go deeper, these are the reference points I return to:

• Gregor Hohpe and Bobby Woolf, Enterprise Integration Patterns. The canonical reference for messaging patterns, including the Canonical Data Model, Dead Letter Channel, Idempotent Receiver and Message Broker patterns discussed here.
• Sam Newman, Building Microservices. Practical treatment of loose coupling, contracts, versioning and the operational realities of distributed systems.
• The pillar overview on this site, enterprise system integration explained, which frames the concepts these mistakes cut against.
• Companion practice guides: integration error handling best practices, integration security best practices, and how to design integration architecture.
• Vendor documentation for whatever platform you are integrating, read for its published, versioned contracts. The Business Central APIs and integrations guide is a worked example of building to a stable public interface rather than internal structures.

Final thoughts

If there is a single sentence to carry out of this, it is that integration failures are almost never failures of technology and almost always failures of foresight. Every mistake in this catalogue is invisible in a demo and painful in production, and every one is prevented by a decision that costs almost nothing when made early and a great deal when made late. Agree a canonical model. Design for failure with retries, dead-letter queues and idempotency together. Consolidate onto a shared layer instead of point-to-point wiring. Instrument everything. Build security and versioned contracts in from the first line. None of it is glamorous, and none of it is hard in isolation. What is hard is having the discipline to do it under schedule pressure, when the happy path already demos and the deadline is close.

That discipline is the actual deliverable of an experienced integration hand. The code is commodity; the tools are excellent; the patterns are documented and public. The value is in knowing, before anyone has written a mapping, which of these mistakes the project is about to make, and quietly closing each door before it becomes a production incident. Get the early decisions right and the rest of the project is calm. Get them wrong and no amount of clever engineering later will fully dig you out.

Related reading: Enterprise system integration explained, Integration error handling best practices, Integration security best practices, How to design integration architecture, Business Central APIs and integrations.