API integration best practices, from the ways integrations fail silently.

The same record arrives twice

A request times out. The integration can't tell whether the other system received it, so it sends it again. Both copies go through, and a customer gets two invoices.

Retrying is correct, because networks fail. The fix is making the retry safe. Each change carries a key that identifies it, and the receiving side refuses to apply the same key twice. Payment providers built their APIs around this pattern: Stripe's documentation, for example, has clients attach an idempotency key to a request so that retrying it can't charge a card twice. When the target system has no such feature, the integration keeps its own record of what it has already applied.

A change never arrives

Webhooks, the messages one system sends another when something changes, are the fastest way to sync. They're also easy to lose: the receiving side was being deployed, a message was rejected once and not retried, or the sender gave up after a few attempts.

An integration that trusts webhooks alone will drift a few records at a time. The fix is a second path: a scheduled read that asks "what changed since the last time we checked?" and picks up anything the webhooks missed. Many platforms offer a change feed built for this, such as the change data capture endpoints in QuickBooks Online and Salesforce.

An old update overwrites a new one

Two systems both let people edit a customer's address. Someone updates it in the CRM at 10:02, and someone else corrects it in the ERP at 10:05. The CRM's change is slower to arrive, lands at 10:06, and replaces the correct address with the old one.

There are two fixes, and most integrations need both. First, decide which system owns each field, and let only that system's changes flow outward. Second, compare versions or timestamps before writing, so an update older than what's already there is set aside for review.

One bad record, logged and forgotten

A batch of 200 orders syncs. One is rejected because a product code doesn't exist in the ERP. The integration logs the error and moves on, and nobody reads the log.

An error log only helps if someone reads it. A business needs a review queue: each rejected record, the reason in plain words, and a named person who owns clearing it. If the queue isn't empty by a set time each day, someone hears about it.

The connection expires

Most modern APIs use OAuth tokens that expire and have to be refreshed. If a refresh fails, or the person whose account authorized the connection leaves and their account is disabled, the integration stops. Some integrations fail loudly when this happens. Many just stop sending, and nothing looks wrong until someone notices the numbers haven't moved.

Connect with a service account the business owns, not a person's login, and monitor the thing that matters: whether data is still flowing, not whether the process is still running.

Someone changes the other system

An administrator adds a new option to a picklist in the CRM, renames a field, or makes a new field required in the ERP. The integration was built against yesterday's version, so it starts rejecting records.

Validate every payload against an agreed definition before writing it, so a change is caught as a clear error the first time it appears. Tests that run the integration against a sandbox copy of each system will catch many of these before production does.

The integration runs out of allowance

Most platforms limit how many API calls you can make, and many share the allowance across every app in the account. HubSpot's daily limit is shared by all the apps in an account. Salesforce gives an Enterprise Edition org 100,000 requests per 24 hours plus 1,000 per user license, for every integration combined. An integration that polls every minute can use up the allowance your other tools depend on.

Listen for changes instead of polling, write in batches, back off when the platform says to slow down, and track consumption so you see the ceiling before you hit it.

The one report that catches all of them

Every failure above shows up in the same place: the two systems stop agreeing. So the most useful thing an integration can do is check.

Once a day, compare counts and totals between the systems: orders, invoices, amounts, customers, stock. When they disagree, name the records that differ and send them to the review queue. This report catches the failures you designed against and the ones you didn't think of, and it turns "we found out at month end" into "we found out this morning".

What that report looks like

An illustrative daily check for a store connected to an ERP:

Nobody reads a report like this when everything matches. It exists for the morning it doesn't, and on that morning it names the records, so fixing them takes minutes instead of an investigation.

When a no-code tool is enough

Not every connection needs this much engineering. A flow in Zapier, Make or Power Automate is a reasonable choice when volume is low, a missed or duplicated record would be noticed and fixed by hand, and the data isn't sensitive. Once money, stock or customer records depend on the sync, the failure modes above start to cost more than the engineering that prevents them.

Questions to ask whoever runs your integrations

1. If a record fails today, who finds out, and how?
2. What happens if the same change arrives twice?
3. How would we know if a webhook was missed?
4. Which system owns each field that moves?
5. Whose account is the connection authorized under?
6. Is there a daily reconciliation, and who reads it?

If the answers are unclear, the integration may be working today, and you won't know when it stops. Our custom API integrations page describes how we build to this standard, and the platform pages cover QuickBooks, HubSpot, Salesforce, NetSuite and Shopify.

Sources

• Stripe: Idempotent requests
• HubSpot: API usage guidelines and limits
• Salesforce: API request limits and allocations