Most of the effort in a typical business software project goes into connecting systems rather than building new ones. And most project overruns come from an integration turning out harder than it looked.
Here is what to check and how to build it.
Before you commit: assess the API
The single most useful thing you can do, and it takes an afternoon.
Does documentation exist and is it current? Documentation referencing an endpoint that returns a different shape is a warning about everything else.
Can you get test credentials today? Not eventually. A vendor that takes three weeks to issue sandbox access will take three weeks to answer a support question.
What can it actually do? Read-only is a very different project from read and write. Check the specific operations you need exist, not just that "there is an API".
What are the rate limits? And are they per second, per minute or per day? A daily cap can make an otherwise simple integration unworkable.
Is there a sandbox, and does it behave like production? Sandboxes routinely differ in ways that surface at launch.
What happens on errors? Are they documented, consistent, and do they use meaningful status codes?
A supplier quoting an integration without doing this is guessing, and the correction arrives as a change request.
Credentials
Never in source code. Never in a client-side bundle. Environment variables or a secrets manager, injected at runtime.
Scope them to the minimum permissions the integration needs. Rotate them on a schedule and when anyone with access leaves. Keep separate credentials for staging and production — a test run that emails your real customer list is a memorable afternoon.
For OAuth integrations, handle token refresh properly and store refresh tokens securely. An expired token at 2am should refresh, not fail.
Timeouts
Set them explicitly on every call. A request with no timeout can hang indefinitely, holding a connection and blocking whatever is queued behind it.
Set them shorter than feels natural. A call that normally takes 300ms and has taken thirty seconds is not going to succeed usefully.
Separate connect and read timeouts where your client supports it.
Retries
Distinguish failure types, because treating them identically causes the main problems.
Transient — timeout, 429 rate limit, 502, 503, 504, connection reset. Retry with exponential backoff.
Permanent — 400 bad request, 401 unauthorised, 403 forbidden, 404 not found, 422 validation. Do not retry; the same request will fail identically forever.
Ambiguous — 500. Retry a bounded number of times, then treat as permanent.
Add jitter to the backoff. Without it, every client that failed during an outage retries simultaneously the moment it recovers, producing a second outage.
Respect Retry-After headers when the API provides them.
Idempotency
The concept that prevents the worst failure mode.
Your request to create a charge times out. Did the charge happen? You do not know. Retrying might create a second one.
An idempotency key is a unique identifier you send with the request. The receiving system records it, and a repeat request with the same key returns the original result rather than performing the operation again.
Many good APIs support this explicitly. Where one does not, approximate it: check whether the record exists before creating, using a reference you control.
Any call that creates, sends or charges needs this. Without it, your retry logic is a duplication machine.
Rate limits
Read the documented limits and build to them rather than discovering them.
- Throttle proactively rather than relying on receiving 429s
- Queue and pace bulk operations instead of firing them in parallel
- Back off on 429, honouring
Retry-After - Monitor your usage against the limit, so you know before you hit it
For high-volume integrations, a token-bucket limiter on your side is worth the small effort.
Webhooks
Receiving events rather than polling is better for both sides, and has its own requirements.
Verify the signature. Most providers sign webhook payloads. Verify before processing, or anyone who learns your URL can send you fake events.
Respond quickly. Acknowledge with a 200 immediately and process asynchronously. Providers time out and retry if you take too long, which means your slow processing creates duplicate deliveries.
Expect duplicates. At-least-once delivery is the norm. Deduplicate on the event ID.
Expect out-of-order delivery. Do not assume event B arrives after event A. Use timestamps or sequence numbers in the payload.
Handle unknown event types gracefully. Providers add new ones; your handler should ignore what it does not recognise rather than erroring.
Data mapping
Where the subtle bugs live.
Dates and times. What timezone? Is it ISO 8601? Does it include an offset? Mismatched timezone assumptions are among the most common and most confusing integration bugs.
Money. Minor units or decimal? Which currency, and is it stated? Floating-point arithmetic on money is a mistake that compounds.
Identifiers. Are they stable? Some systems reuse IDs after deletion.
Optional fields. A field present in the documentation and absent in practice should not crash your handler.
Enumerations. New values get added. Handle unknown values without failing.
Logging
When something goes wrong — and it will — you need to reconstruct what happened.
Log the request, the response status, timing, and a correlation ID threaded through your own systems. Redact credentials and personal data before logging, which is easy to forget and awkward to discover later.
Keep enough history to debug something that failed last week, with a retention policy so logs do not grow unbounded.
Testing
Sandboxes lie. They are cleaner, faster and more forgiving than production. Test against realistic data volumes and realistic data mess before launch.
Test the failure paths deliberately: revoke a credential, point at an unreachable host, send malformed data, simulate a rate limit, kill the connection mid-request. Confirm your retries, timeouts and alerts behave as designed.
Versioning and change
APIs change. Build for it.
- Pin to a version where the provider offers versioning
- Subscribe to their changelog and deprecation notices
- Monitor for unexpected response shapes — a field that quietly disappeared will otherwise surface as a confusing downstream bug
- Abstract the integration behind your own interface, so a provider change touches one module
A checklist
For every integration that matters:
- API assessed before committing to a price
- Credentials in a secrets store, scoped minimally, separate per environment
- Explicit timeouts on every call
- Retries with backoff and jitter, only on transient failures
- Idempotency on anything creating, sending or charging
- Rate limits respected proactively
- Webhook signatures verified, fast acknowledgement, deduplication
- Date, money and identifier handling verified explicitly
- Logging with correlation IDs and redaction
- Failure paths tested, not assumed
If you want an integration built properly, or an existing one audited for these, get in touch.
