Fixing API errors for good: six steps that stop the repeats

An order does not come through. Customer records sit in a queue. Stock levels suddenly stop matching reality. The log might say nothing more than 500 Internal Server Error, but on the shop floor the impact is immediate, because somebody is about to fix it by hand.

For organisations that run on integrations between a webshop, ERP, CRM, payment provider, logistics system and their own platform, an API is not a technical detail. It is an operational link. When that link falters, manual work appears, processes fall behind and the pressure on support and operations goes up.

Dealing with API errors structurally therefore means more than resending a request or nudging a timeout upwards. You want to know what is failing, why it is failing, and who makes sure the same problem does not come back next week.

Why the error message is rarely the real problem

An error code is a symptom. A 401 can mean that credentials have expired, but just as easily that something changed in the access rights or that a process is quietly pointing at the test environment. A 429 tells you a limit has been reached, but not whether your application is firing off more requests than it needs to or whether the limit simply does not match your volumes. And with a 500, the cause can sit in your own code, in an external service, in the infrastructure, or in a combination nobody saw coming.

React to the error code alone and you fix today's outage. Look at the whole chain and you prevent next month's. That is the difference between incident management and structural maintenance.

Every integration involves at least four layers: the data you send, the application that builds the request, the network and hosting underneath it, and the system on the receiving end. A fault can start at any of them, and sometimes only in combination. An apostrophe in a surname, a date format that gets interpreted slightly differently and an update on the supplier's side can together cause a problem that no isolated test would ever surface.

Start with context, not with the code

During an active outage you restore service first, obviously. But once things are running again, the key question is not how to make that one request go green. The question is whether you can reconstruct the incident. Without context an error message stays guesswork, certainly when several systems and parties are involved.

So capture enough on every API call to tell the full story later: a request ID, the timestamp, the endpoint, the version used, the response code and the technical cause. Do not write away complete payloads by default, because those quickly contain personal data, tokens or commercially sensitive information. Stick to what you genuinely need for analysis: field names, validation errors, correlation IDs and masked values.

That correlation ID may well be the most underrated part of the setup. It gives a single transaction a recognisable trail across every system it touches. When an order leaves your platform and gets stuck at the fulfilment partner, you do not want to scroll through thousands of log lines. You want one search to show you which step gave out, and when.

With that foundation in place, the following six steps are worth taking.

1. Separate temporary failures from permanent ones

Not every error deserves the same response. A brief network drop or a server that is momentarily overloaded recovers perfectly well on a second attempt. A missing mandatory field, an invalid VAT number or an expired API key does not. You can retry a thousand times and the answer stays the same.

Sort errors into at least three categories: temporary, functional and structurally technical. Temporary failures can be retried automatically. Functional errors belong back with the user or the department that can correct them. Structurally technical errors call for investigation, a change, and a test that proves the problem is actually gone.

Automatic retries are useful, then, but only within limits. Increase the wait between attempts, cap the number of tries and make sure hundreds of processes do not keep hammering the same external API at once. For payments and order creation you need idempotency on top of that: a repeated request must never produce a second charge or a duplicate order.

2. Make error messages something you can act on

A technical code is often enough for a developer. For operations or customer service it is not. Compare Validation failed with Order 84721 was not sent: field houseNumber is missing from the delivery address. With the second message, someone knows what to do without involving IT.

Work with two levels, in other words. Outward facing, keep the message understandable and safe, without exposing internal details. Internally, keep exactly what you need to find the cause: the stack trace, the message from the receiving side and the fields that validation tripped over, with sensitive values masked. That saves a lot of screenshots of cryptic messages being passed around before anyone can start investigating.

Keep a sense of proportion while you are at it. If every deviation triggers a critical alert, your team will be looking straight past them within a fortnight. A sync that will run again automatically tonight deserves a different signal than a payment API that is down for every customer.

3. Check the contract, not just the code

Plenty of API problems start with a change that is entirely reasonable in itself. A supplier makes a field mandatory, an enum gains an extra value, an endpoint moves to a new version or a date format gets validated more strictly. If your integration quietly assumes the old behaviour, the process breaks at a moment you did not plan for.

Treat the API specification as a contract. Write down which endpoints, fields, versions, limits and error codes you expect, and when something changes, do not only test the happy path. Incomplete data, duplicate requests, timeouts and malformed responses are where the interesting results come from.

Contract tests are practical here, because they check that both sides still honour the agreement without needing a full acceptance environment. Setting them up properly takes time. You earn that time back the first time a change is caught before it reaches your order processing or customer portal.

4. Point your monitoring at business impact

A server that responds does not mean your process is running. An API can return a perfectly polite 200 OK while the data itself is rejected further down or parked in a queue. So with uptime and server monitoring, look beyond availability and response time and measure the outcome of the chain as well.

Count how many orders actually synchronised, how many invoices are stuck in processing and how many requests fail per error category. Watch the trends above all. A handful of 429 responses a day can be completely normal, but a line that has been climbing for three weeks is telling you that volumes, caching or request behaviour need attention before the integration falls over at the first peak.

Pick thresholds that fit the process. In a real time payment flow, a few minutes of downtime is already too much. For an overnight product import there is room for a recovery window, as long as the errors stay visible and someone picks them up the next morning.

5. Give the whole chain a single owner

The most frustrating API outage is rarely the hardest one technically. It is the incident where three suppliers point at each other: the software builder says it is the hosting, the host points at the external API, and that party asks for logs nobody has to hand. Meanwhile your process is standing still.

Solving things structurally calls for ownership of the full chain. That does not mean one party can prevent every external outage, because nobody can. It does mean somebody coordinates the incident, gathers the facts, approaches the right party and makes sure the temporary workaround gets replaced by a lasting fix.

It is also why, in our view, development, hosting and technical maintenance should not sit completely apart from each other. When the same partner has sight of the application, the infrastructure and the monitoring, the route to the cause is a good deal shorter. That is how LJPc works: not passing tickets along, but establishing where the process breaks and repairing it there.

6. Turn every incident into one specific improvement

The moment everything is running again, everyone wants to move on. Understandably, since day to day operations have been waiting too. Yet that is exactly when all the information you need to prevent a repeat is still on the table, and a week later half of it has evaporated.

Take half an hour to go through what happened, how it came to light, why the existing checks did not catch it sooner and which measure will catch it from now on. Sometimes that is a code change. Just as often it is stricter validation before sending, an alert on unusual volumes, a different retry strategy or a few concrete agreements with an external supplier.

Keep the follow up small and verifiable. Improve monitoring is not an action. Send an alert when more than five percent of stock updates fail within fifteen minutes is. Tie each improvement to a test or a measurement, so you can see that the problem is genuinely solved and not just administratively closed.

What if there is no time for any of this?

During an active outage, speed is rightly in charge. Customers cannot check out, orders are stuck, a platform is unreachable. Restoring service, falling back to a previous version or switching to a safe manual route is exactly the right call at that point.

Just do not treat the emergency measure as the end of it. A manual export, an extra retry or a scheduled restart can save the operation while the underlying fault carries on untouched. So book time for analysis straight after recovery. If you do not, the workaround quietly becomes part of the process and the risk grows along with it.

An integration does not have to be flawless, and it never will be. External systems change, networks hiccup and data is sometimes simply messy. What matters is that errors show up quickly, stay manageable and lead to an improvement you can point at. Then an API error stops being a recurring disruption and becomes useful information about your own operation.