API integrations: six mistakes that cost money
An integration that works in testing and misbehaves in production almost always has one of six faults. None of them are about which API you use; they are about how the system behaves when something goes wrong: when the receiver is down, when the same message arrives twice, or when a field means different things in the two systems.
1. Direct calls without a queue
A direct call between two systems works until one of them is down, at which point the transaction is lost. With a queue in between, the event is stored, retried with increasing backoff, and moved to a dead letter queue if it ultimately fails. That is the difference between an integration that needs watching and one that does not.
2. Retries without idempotency
The moment you add retries, the same message can arrive twice. If the operation is not idempotent, every replay creates a duplicate order. The fix is for the receiver to identify the event on a key and ignore it if already processed. This is the most expensive mistake on the list because the customer finds it, not you.
3. Field mapping nobody reviewed
The real difficulty is rarely the technology but that fields mean different things in the two systems. "Delivery date" might be promised, planned or actual. Write the mapping as a table the business can read and argue with before it becomes code. Correcting it there is cheaper than correcting it in production.
4. No alerting on silence
Most people alert on errors. Fewer alert on nothing happening. An integration that has stopped running entirely produces no error messages at all, and gets discovered when somebody wonders where this week’s orders went. Alert on the queue growing and on too long since the last successful run.
5. Real time when same day would do
Real time in both directions is expensive to build and expensive to debug. Ask what actually happens if the data is ten minutes old. Usually nothing. If the system supports webhooks you get real time nearly free; if it does not, polling every fifteen minutes is almost always enough and far easier to reason about.
6. No plan for the format changing
The other system will be updated. Fields get renamed, become optional, disappear. An integration assuming the response always looks the same breaks quietly and writes wrong data. Validate the response against an expected shape and alert when it does not match, instead of letting a missing field become an empty string in the ERP.
Common questions
Our ERP has no API. Can it still be integrated?
Often yes, but at a lower level. Without an API you can work against the database directly, against file or SFTP exports, or against an import routine in the system. It is slower and more brittle than a real API, and that brittleness should be stated up front so expectations match what can actually be promised.
How often should data synchronise?
If the system supports webhooks, synchronisation happens within seconds of a change. If not, it becomes scheduled polling, typically every five to sixty minutes. Ask what actually happens if the data is ten minutes old; the answer is "nothing" more often than people expect, and then real time is a cost without a benefit.
How do we find out an integration has stopped working?
Only if you alert on silence. Most people alert on errors, but an integration that has stopped running entirely produces no error messages at all. So alert on the queue growing and on too long since the last successful run, or you find out when somebody wonders where this week’s orders went.
