API integration is the part of a platform build most dependent on someone else's cooperation, and the most reliable source of delay. The root cause is rarely technical difficulty — it is unspecified expectations. This page provides the checklist in three stages: before, during and after.

Before integration: three questions, non-negotiable

1. What is the documentation version, and when was it last updated? Stale documentation is the single largest contributor to integration slip. Check the version and date first; anything more than six months old should be re-confirmed in writing.
2. Can the sandbox reproduce production edge cases? An empty sandbox tests nothing. Require an environment with boundary data, or at minimum an importable seed set.
3. Who is the counterpart, and how fast do they respond? "Contact tech support if you have questions" means there is no counterpart. Get a name, a time zone and a response-time expectation — in the contract if possible.

During integration: three traps

Trap one: signature verification

Of ten failed integrations, four die here. The usual causes: parameter-sorting rules differ (lexicographic order, case sensitivity), timestamp tolerance is misaligned (aim for ±300 seconds), or encoding differs (how URL encoding treats spaces). The fix is unglamorous: compare your signature string against their sample code byte by byte, and align before anything else.

Trap two: idempotency

Retry-after-timeout is daily life in distributed systems. If an endpoint is not idempotent, one retry becomes two orders. Ask before integrating: is this endpoint idempotent, and what is the idempotency key? No answer means treat it as non-idempotent — generate your own unique request ID and send it along.

Trap three: timeouts and retries

Do not guess timeouts. Read timeout of 3-5 seconds, two to three retries, exponential backoff (1s, 2s, 4s). Past three failed retries, route to a human queue — do not let the machine keep insisting.

After integration: acceptance by error codes

Run a dedicated fault-injection round at acceptance: malformed parameters, expired signatures, simulated timeouts. "The happy path works" is half the acceptance — the error path is what operations lives with daily.

Three conventions beyond error codes

• Time format: ISO 8601 in UTC. Reject formats like "yyyy-MM-dd" that carry no zone.
• Pagination: cursor pagination beats page numbers, especially on large lists.
• Callbacks: callback URLs must be publicly reachable, and the retry policy for failed callbacks belongs in the documentation.

Where this connects

Retry, circuit-breaking and degradation policies at the interface layer are architecture topics — see high-availability architecture. Signature algorithms and key management are covered in the security topic. For how much buffer an integration stage needs, see the timeline breakdown — the two-weeks-planned-five-weeks-actual figure there is exactly what this checklist exists to prevent.

A lesson from a real project

One project we watched last year lost four full weeks in integration for a reason that sounds trivial: both sides implemented the signature algorithm correctly, but one URL-encoded spaces as "+" and the other followed RFC 3986 and encoded them as "%20". Two characters of difference, four weeks of calendar. The general lesson: the first integration task is not business logic. It is aligning the plumbing — signatures, timestamps, encoding — with a minimal request. Only after that do functional tests run at a sane pace.