API integration troubleshooting: a practical repair checklist

When an integration stops working

A dashboard can show a green request while a CRM record is missing. A job can report a timeout after the destination already accepted a write. Reconnecting every account or replaying every event can make those situations harder to untangle. This checklist is for an engineer or delivery owner investigating one bounded failure—not a replacement for the provider’s documentation or your change-control process.

1. Define the missing business result

Write down what should have happened: one CRM record created, one invoice updated, or one approved notification delivered. A successful HTTP response alone is not proof that the downstream business result occurred. Identify the owner who can confirm the correct result.

2. Capture one trace, not the entire customer database

Record the environment, timestamp with timezone, source event or request ID, destination, status and sanitized error. Compare the same identifiers at each hop: sender, endpoint, queue, worker and destination. Preserve relevant evidence before changing settings; do not put secrets or personal records into an email or public issue.

3. Locate the first divergence

Compare one authorized failing example with a successful example. Did the source emit an event? Did the endpoint receive it? Was it durably queued? Did the worker process it? Did the destination accept and retain the intended change? Check environment and API-version mismatches before changing business logic.

4. Separate transport errors from business rules

An authentication failure, schema mismatch, rate limit and rejected business transition need different repairs. Use the provider’s documented error codes and request IDs. A valid payload may still violate an application rule. Do not treat every failure as a reason to increase retries.

5. Decide whether retrying is safe

A timeout leaves an important question: did the remote system commit the change before the connection failed? Inspect the destination or use the provider’s documented reconciliation mechanism before replaying writes. Use supported idempotency controls consistently for the same operation, not a new key on every attempt.

6. Turn the finding into a small test

Use an authorized development environment and a minimal sanitized fixture. Cover the original failure and at least one unchanged successful path. For event-driven work, include repeat delivery, out-of-order arrival, temporary destination failure and worker restart where relevant. Agree which effects must occur once, which can repeat, and which must never occur.

7. Separate a tested patch from permission to deploy

Record the patch, test results, unresolved assumptions and rollback steps. An approved repair branch is not permission to replay a production backlog. Deployment and replay require an owner, an explicit scope, a recovery plan and verification of the actual destination state.

Example: the same webhook arrives twice

This is a synthetic example, not a customer result. Suppose an event requests creation of a CRM task. The destination creates the task, but the worker loses its connection before recording completion. A retry that blindly creates another task can produce a duplicate.

The investigation should distinguish the event identity, the intended business operation and the destination record. Test recovery after a partial success and concurrent delivery. A local “seen event” flag alone can fail if it is written before a failed downstream action, or after an action that succeeded just before a crash. The appropriate transaction, outbox or reconciliation design depends on the systems you control.

Provider-specific details matter

For Stripe webhooks, verify signatures using the unmodified request body. Delivery order is not guaranteed, and duplicate events can occur. These are reasons to test your handler’s behavior rather than assume a happy-path request represents the full workflow. See Stripe’s webhook documentation.

Stripe’s API also supports idempotency keys for POST requests. Its retention and parameter-matching rules matter; that mechanism is not a general guarantee that every downstream side effect happens exactly once. Review the idempotent-request documentation for the endpoint you use. Other providers have different contracts.

What to put in a repair ticket

Include the expected and actual result, affected environment, last known successful run, sanitized error and request ID, recent changes, business impact, and the person who can approve the work. Identify existing tests and the constraints on access. Leave credentials, customer records and confidential logs out of initial email.