API Integration Services That Handle Failure Properly

Why do integration estimates slip so reliably?

API integration estimates slip because teams scope the first successful request instead of production behavior. The real work includes credential renewal, rate limits, idempotent writes, ambiguous failures, webhook verification, reconciliation, and searchable logs. Count operations and failure paths before assigning a timeline, especially when an API can move money or create records.

The actual work is in the states nobody demonstrated. What happens when the call times out but the vendor did process it. What happens when you hit a rate limit halfway through a batch. What happens when the vendor returns a two hundred status with an error inside the body, which is more common than it should be. What happens when a field the documentation describes as always present is absent for one customer.

Then there is the mismatch between the vendor's model and yours. Their customer object has fields yours does not and lacks fields yours requires. Their status values do not map cleanly onto your states. Their identifiers are not the ones your users know. Resolving that is design work, not plumbing.

A useful rule when estimating: whatever the happy path takes, the production-ready integration takes five to eight times longer. That multiplier sounds absurd until you have shipped a few, and then it stops sounding high.

What does the work actually consist of?

Authentication and credential lifecycle. OAuth flows with refresh handling, API key rotation, and whatever bespoke scheme older vendors use. Tokens expire at inconvenient times and the handling has to be automatic, because a manual refresh is an outage waiting for a weekend.

Rate limits, treated as a design constraint rather than an error. Learn the limit, respect it proactively with a queue or a token bucket, and back off exponentially with jitter when you are throttled anyway. Discovering rate limits in production during a busy period is a common and avoidable incident.

Retries with idempotency, which is the single most important thing on this list. Any write that can be retried must carry an idempotency key so the vendor can recognise a repeat. Without it, a timeout on a payment call becomes two payments, and finding out which happened requires a reconciliation you have not built yet.

Error taxonomy. Sort failures into transient, meaning retry; permanent, meaning stop and surface it; and ambiguous, meaning check the state before doing anything. Ambiguous is the dangerous category and it is where the interesting bugs live.

And observability. Log every request and response with a correlation identifier, keep them long enough to investigate a dispute, and redact anything sensitive on the way in. When a customer says an order never reached the warehouse, you want to answer from data rather than from memory.

How should webhooks be handled?

Verify the signature before doing anything else, and reject anything unsigned. An unauthenticated webhook endpoint is an open write path into your system, and it is a surprisingly common oversight.

Acknowledge fast and process asynchronously. Return a success status immediately and put the payload on a queue. Vendors treat a slow response as a failure and retry, so doing real work inside the request handler produces duplicate processing under load, which is exactly when you least want it.

Assume duplicates and out-of-order delivery, because both happen routinely. Deduplicate on the event identifier and use the vendor's timestamp or version rather than arrival order to decide whether an event is stale. An old status arriving after a new one should not overwrite it.

And build the reconciliation job regardless. Webhooks get lost, for reasons ranging from your own deploy window to the vendor's outage. A scheduled job that compares your state against theirs and repairs differences is the difference between a system that drifts silently and one that corrects itself. This is the single most valuable thing most integrations are missing.

Do you need an integration layer?

For one or two integrations, no. Put them in your application with clean boundaries and move on. Building infrastructure for a problem you have twice is premature.

Past about four integrations, or when several systems need the same data, a dedicated layer starts earning its place. What it gives you is one place where retries, rate limiting, credential storage, and logging are implemented once rather than repeated with subtle differences in each integration. The subtle differences are the problem it actually solves.

Whether that layer is an integration platform product or a small service you own depends on volume and how unusual your transformations are. Platform products handle standard connections quickly and become awkward when the mapping needs real logic. A service you own is more work up front and does not have a ceiling.

Either way, define your own canonical model in the middle. Every vendor maps into your shape, never the reverse. A schema shaped like whichever API arrived first is a decision you will pay for at the second and third one.

How do you assess an API before committing?

Read the error documentation rather than the getting-started guide. Every vendor makes the first call easy. A vendor who documents their error codes, rate limits, retry semantics, and idempotency support has thought about production use. One whose documentation ends after authentication has not.

Check whether there is a sandbox that behaves like production, including its failures. A sandbox that only returns success is worse than no sandbox, because it produces confidence you have not earned.

Look for a public status page with history. Not because outages are disqualifying, everyone has them, but because a vendor who publishes incident history is a vendor who expects to be held to it.

And test the failure cases yourself during evaluation. Send a malformed request, exceed the rate limit deliberately, and revoke a token mid-session. How the API behaves when things go wrong tells you more about the integration cost than any amount of documentation.

How do you scope an integration honestly?

Count the operations, not the vendors. Three read endpoints and one write is a small piece of work. One vendor with twelve operations, two of which move money, is not. An estimate that says one week per integration regardless of what the integration does is not an estimate.

Weight the writes heavily. Reads that fail can be retried without consequence. Writes that fail ambiguously require idempotency, reconciliation, and a defined recovery path, and that is where most of the engineering time goes.

Add explicit time for the vendor's specific weirdness, because there always is some. Undocumented required fields, inconsistent date formats, a status value that appears in practice but not in the specification. Nobody can predict which one it will be, and it is a mistake to plan as though there will not be one.

And insist that reconciliation is in scope from the start rather than added later. It is the thing that gets cut under time pressure and the thing whose absence causes the incident six months on. Custom software development cost covers how integrations shape overall project bands.