API integration troubleshooting: a practical guide to fixing broken calls

When an integration breaks, the fastest route to a fix is to stop guessing and follow one failing request from your code to the provider's server and back. Broken integrations nearly always trace back to the same handful of causes: authentication, rate limits, retry and delivery behaviour, payload shape, environment differences, or a change on the provider's side that nobody told you about. Work through them in that order and you end up fixing a cause rather than guessing at symptoms.

Start with one failing request, end to end

Broken integrations get debugged badly because people start in the middle: reading application code, re-reading provider documentation, changing two things at once. Start at the edge instead, with one concrete request you can point at.

1. Capture the failing call in full: method, URL, headers with secrets redacted, request body, response status, response headers and response body, plus a timestamp.
2. Attach a correlation ID to every outbound request and log it on both sides of the boundary. Most providers echo their own request ID in a response header. Record both.
3. Replay the same request with curl or a REST client, outside your application. If it fails there too, the problem is the request or the provider. If it succeeds, the problem is your code, your configuration or your environment.
4. Check the provider's own log or developer dashboard for that request ID. Their view of the call often carries a validation message your client never surfaced.
5. Change one variable at a time: one header, one field, one credential. Two changes at once turn a diagnosis into a guess.

Keep the captured request in the ticket. When the same failure returns months later, that artefact saves the next person the slowest part of the work.

What the status code is actually telling you

Status codes are coarse, and providers apply them inconsistently, but they still cut the search space down. Read the code, then read the response body, because the body usually carries the specific field or rule that failed.

A 200 response with an error object in the body is still a failure. Parse the payload, not just the status line.

Auth and token expiry: the failures that lie

Authentication problems are the most common and the most misread, because a 401 rarely means what the log says it means. Expired access tokens, rotated refresh tokens, revoked scopes, a key copied from the sandbox, and clock skew all surface as the same terse message.

Work through it in a fixed order. Confirm which environment the credential belongs to. Confirm the header format, including the scheme word before the token. Decode the token if it is a JWT and read the expiry and issuer claims rather than trusting your refresh logic. Check the machine clock: signed requests and short-lived tokens fail on a server whose clock has drifted, so make sure time sync is running.

Then fix the pattern, not the incident. Refresh proactively, once a token passes roughly 80 percent of its lifetime, instead of waiting for a 401. Hold a lock around refresh so concurrent workers do not each request a new token and invalidate one another. Log the expiry timestamp, never the token. Treat a refresh failure as a distinct alert, because a rotated or revoked credential will not fix itself.

Rate limits, retries and idempotency

Retries are where a small outage becomes a large one. A client that retries immediately, in a tight loop, across every worker, turns a brief 429 into a sustained block.

Respect Retry-After when the provider sends it. Otherwise back off: delay = min(cap, base × 2^attempt) + random jitter, with a hard cap on attempts and a dead-letter queue for what still fails. Jitter matters more than the curve, because it stops every retry in your fleet firing on the same tick.

Retry only what is safe to repeat. Reads and idempotent updates are fine. Anything that creates a record, charges a card or sends a message needs an idempotency key: a stable value you generate per logical operation and send on every attempt, so the provider returns the original result instead of creating a second record. Where the provider offers no such key, keep your own outbound log and check it before resending.

Webhooks are the same problem from the other direction. Providers retry deliveries until they get a fast success, so duplicates and out-of-order events are normal traffic. A durable handler does five things in order: verify the signature, check the event ID against a de-duplication table, acknowledge with a 200 straight away, queue the real work for a background worker, and only then process. Compare a version or updated timestamp before writing, so a stale redelivery cannot overwrite newer state. Log every rejected delivery with its reason; a wall of signature failures usually means a rotated signing secret rather than an attack.

Payload drift and environment gaps

The hardest integration bugs are the ones where nothing errors. A provider adds an enum value, changes a decimal to a string, makes an optional field nullable, or moves to cursor pagination, and your mapping quietly writes a null into a field the business depends on.

Validate responses at the boundary against a schema and fail loudly when they do not match, rather than letting a malformed record travel three layers into your domain logic. Log unknown fields at a low level so you can see additions arriving. Pin the API version explicitly in the request instead of following whatever the default has become, and subscribe to the provider's changelog with a real person's inbox behind it. Keep the field mapping in one place, documented, so a rename is a one-line change and not an archaeology project. This is ordinary integration architecture discipline, and it pays for itself the first time a supplier ships a breaking change on a Friday.

Sandbox environments deserve their own suspicion. They often run an older version, return stubbed values, skip validation rules and enforce different limits. Anything that behaves in sandbox and fails in production is usually a version, a validation rule or a volume difference. Run a small live smoke test against production before launch, and keep credentials, base URLs and webhook endpoints in configuration rather than in code so nobody ships the wrong pair.

Monitoring so you find out before the client does

Uptime checks tell you the site is up. They say nothing about the integration that has been failing silently since Tuesday. Instrument the boundary itself.

Track error rate and latency per provider and per endpoint, retry counts, dead-letter queue depth, and the age of the most recent successful call and the most recent webhook received. Staleness is the signal that catches quiet failures: if a feed that normally delivers every hour has been silent all morning, that is an incident even though nothing errored. Run a synthetic canary call on a schedule against a cheap read endpoint. Alert on the things a human can act on, route them to somebody who is actually on shift, and keep a short runbook next to the alert with the replay steps above. Teams that pair this with end-to-end ownership of the stack catch integration faults themselves instead of hearing about them in a client email.

How OlDevs helps

OlDevs has been building and repairing integrations from Vancouver since 2014, across payments, CRMs, booking systems, ERPs and internal services. We work as one accountable team, ship a working demo every week, and hand over code, designs, accounts and IP that you own outright. A typical engagement starts with an audit of your existing boundaries: credential handling, retry and idempotency behaviour, schema validation, webhook durability and monitoring coverage, with a prioritised list of what to fix first. From there we can harden what you have or rebuild the integration layer as part of broader web app development work, with WCAG 2.2 AA accessibility and bilingual EN/FR capability where you need them.

If an integration is failing now, or you want to know where the next one will break, request a quote. We reply to every enquiry within one business day.