Five API Integration Mistakes We See Over and Over

We have built and maintained API integrations with probably sixty or seventy different third-party services at this point. Payment processors, shipping carriers, accounting software, CRMs, inventory systems, government databases — the specifics vary but the same patterns of failure keep showing up regardless of the industry or the API being integrated.

Here are the five mistakes that cause the most problems.

1. Not handling rate limits properly

Every API has rate limits — a maximum number of requests you can make per second, minute, or hour. Most developers know this in theory but do not build proper handling into their code until they hit the limit in production and things break.

The right approach is to implement exponential backoff with jitter from the beginning. When you get a 429 (Too Many Requests) response, wait an increasing amount of time before retrying — one second, then two, then four, with some randomness added so that if multiple processes hit the limit simultaneously they do not all retry at the exact same time.

Also read the API documentation carefully for rate limit headers. Most well-designed APIs return headers like X-RateLimit-Remaining and X-RateLimit-Reset that tell you exactly how many requests you have left and when the window resets. Use this information to throttle proactively rather than waiting to get rejected.

2. Treating the API as always available

Third-party APIs go down. Their servers have maintenance windows. Their SSL certificates expire on a Friday evening. Their data center has a network blip. If your application crashes or hangs when a third-party API is unavailable, you have a fragile system.

Design your integrations with the assumption that the API will be unavailable at some point. Use timeouts on every request — both connection timeouts and read timeouts. Implement circuit breakers that stop sending requests after repeated failures and periodically check if the service has recovered. Queue non-urgent operations so they can be retried later.

Most importantly, make sure your application degrades gracefully. If the shipping API is down, the user should still be able to place the order — just show them a message that shipping estimates are temporarily unavailable and calculate them later.

3. Not logging API interactions

When something goes wrong with an API integration — and it will — you need to be able to see exactly what request you sent and what response you got back. If you are not logging this, you are debugging blind.

Log the full request and response for every API call. This includes the URL, headers (minus sensitive ones like API keys), request body, response status code, response body, and the time the request took. Store these logs for at least 30 days. When a customer reports that their order did not sync to the accounting system, you should be able to pull up the exact API call and see whether the request failed, the response was unexpected, or the data was malformed.

One important caveat: be careful about logging sensitive data. Redact credit card numbers, social security numbers, passwords, and similar fields before writing them to your logs. Having good debugging capability is important, but not at the cost of a data breach.

4. Not versioning your integration

APIs change. Fields get renamed, endpoints get deprecated, response formats evolve. If your integration is tightly coupled to the current API format with no abstraction layer, every API change becomes an emergency.

Build a thin adapter layer between your application and each third-party API. This layer translates between the API's format and your internal data model. When the API changes, you update the adapter — not every piece of code in your application that touches that data.

Also subscribe to the API provider's changelog or developer newsletter. Most API breaking changes are announced weeks or months in advance. If you are caught off guard by a breaking change, you were not paying attention to the communications.

5. Doing synchronous API calls in the request path

This is the most architecturally consequential mistake. A user clicks "Submit Order" in your application, and your server synchronously calls the payment API, then the inventory API, then the shipping API, then the accounting API — all while the user waits. If any of those APIs is slow (or down), the user gets a timeout or a spinning loader.

For most API interactions, the user does not need to wait for the external call to complete. Process the payment synchronously (the user does need to know if that succeeded), but queue the inventory update, shipping label creation, and accounting sync to happen asynchronously in the background. Return a fast response to the user and let the background workers handle the rest.

This makes your application faster, more resilient to third-party outages, and easier to debug when something goes wrong with one specific integration.

The common thread

All five of these mistakes share a common root: building the integration for the happy path and not thinking about what happens when things go wrong. The happy path is easy. The value of a well-built integration is in how it handles the inevitable failures, changes, and edge cases.

If you are building an integration and want to make sure you are covering the bases, we are happy to review your approach before you ship it to production.