Around the call
What a reliable call to an API you do not own needs around it
The call itself is the easy line. These are the parts that decide whether it is safe to depend on — and the branch is the response you did not plan for, which arrives eventually from every provider.
01
Idempotency on the way out
Each call carries a key so that sending it twice — after a timeout you were unsure of — is treated as once, not as a second payment or a duplicate order.
- Idempotency key
02
Timeouts and backoff
A slow provider must not stall your whole system; the call has a deadline, and a failure is retried on a widening interval rather than hammered instantly.
- Timeout
- Backoff
03
Handling the unexpected response
Providers return errors, partial data and shapes their docs never mentioned; the integration decides deliberately what to do with each instead of assuming the happy path.
- Error mapping
04
Drift detection
The response is checked against the contract we hold, so a field the provider quietly renamed is caught by a monitor rather than by a customer whose payment silently failed.
- Contract test
- Monitor
The dead-letter path
A call that cannot be completed even after retries is not dropped; it is set aside with its context for a person to resolve, so a provider outage becomes a queue to work through rather than lost transactions nobody can reconstruct.
The call that works in the demo is not the integration; the integration is what it does at the moment the other side misbehaves.
Why integrations break
The integration that broke because the other side changed
The failure that surprises teams is not the one they wrote. It is that the provider on the other end changed something — a field, an error code, a rate limit, an authentication rule — and told nobody, or told an inbox that was not read. Because you do not control that API, you cannot stop the change; you can only decide whether you find out from a monitor or from a customer. An integration built to assume the contract is fixed is an integration with a delayed fault, because the contract belongs to someone else and they will eventually change it.
So we build the integration behind an isolation layer whose only job is to translate between the provider's contract and yours. Your code speaks to that layer, not to the provider directly. When the provider changes, the repair is confined to one place instead of spreading through every part of your system that touched the API, and a set of contract tests fails loudly the moment the provider's responses stop matching what we agreed to expect. The provider will still change; the difference is that it becomes a contained, visible piece of maintenance rather than a mystery outage.
How we connect
How we connect to a provider's API so their change is not your outage
The order is deliberate: understand what the provider actually guarantees before writing code, and put the defences in before the integration carries anything that matters.
Read the contract and its limits, not just the happy path
We map what the provider guarantees, its rate limits, its error codes and its authentication rules, because the parts that break an integration are usually in the paragraphs a first read skips. A clear picture of what the provider promises and what it does not.
Build the isolation layer
We put a boundary between the provider's shape and your code, so the rest of your system never depends on the provider's exact contract and a change lands in one file. A single place the provider is allowed to affect.
Make retries and idempotency safe
We add the keys and the backoff that let a call be retried after an uncertain timeout without charging twice or posting a duplicate, because a naive retry is often worse than the original failure. A retry that recovers instead of duplicating.
Watch for drift and failure
We run contract tests and monitor the live responses, so a renamed field or a rising error rate is an alert to your team rather than a discovery your customers make first. A warning before the symptom reaches a customer.
Our role
What we take responsibility for and what stays the provider's
- 01
The reliability around the call
We own the retries, idempotency, timeouts and error handling that decide how your system behaves when the provider is slow, wrong or down — the part you can control even though the API is not yours.
- 02
A change you find out about first
We build the drift detection and the isolation layer so a provider change is a monitored, contained repair, and leave your team the tooling to see the integration's health rather than infer it from complaints.
- 03
The provider's guarantee stays theirs
What the API promises, and whether it stays available, remains the provider's responsibility; we are honest that no engineering on your side makes their uptime yours, and we design so their failure degrades gracefully rather than taking you down with it.
Which providers you depend on, and the commercial terms of their availability, are yours to choose; we build the layer that keeps their failures and their changes from becoming your outages, and are clear about the line where their guarantee ends and no code of ours can extend it.
Common questions
What buyers ask
What happens when a third-party API is slow or returns an error we did not expect?+
That is exactly the case the integration is designed around, not an edge case. A slow provider is given a deadline so it cannot stall your own system, and a failed call is retried on a widening interval rather than hammered. Responses the provider's documentation never described — partial data, an unfamiliar error code, an empty body where a record was expected — are mapped to a deliberate decision instead of crashing on an assumption. If a call still cannot complete after its retries, it goes to a dead-letter queue with its context so a person can resolve it, which turns a provider outage into a backlog you work through rather than transactions that silently vanished.
How do you keep an integration working when the provider changes their API?+
You cannot stop a provider changing an API you do not own, so the aim is to make the change cheap and visible rather than impossible. We put an isolation layer between the provider and your code, so their contract is only known in one place; when they change a field or an error, the repair is confined to that layer instead of rippling through everything that touched the API. Alongside it, contract tests check the provider's live responses against what we agreed to expect, so a quiet rename triggers an alert to your team rather than a failure a customer reports. The change still happens; it becomes a small, contained maintenance task with a warning, not a mystery outage discovered downstream.
Why wrap a third-party API in a layer instead of calling it directly from our code?+
Because a direct call spreads a dependency you do not control across your whole codebase. If forty places call the provider directly, then the provider's next change, or a decision to switch providers, is forty edits and forty chances to miss one. A thin layer that translates between the provider's shape and yours means your code depends on your own stable interface, and the provider is only known in one file. It also gives the retries, idempotency and error handling a single home instead of being reimplemented, inconsistently, at every call site. The cost is one layer of indirection; the return is that a provider change, an outage response, or a migration to a different provider is contained rather than a project.
In this cluster
Next step
Harden an integration
A review of an integration you depend on that names its failure behaviour, its retry and idempotency handling, and how you would learn the provider changed it.

