Write the failure modes before the happy path
Integration designs that only document success responses leave on-call engineers guessing when partners time out or send duplicates.
Most partner onboarding decks celebrate a green “200 OK” screenshot. In production, the expensive hours sit elsewhere: timeouts mid-batch, duplicate webhooks after a retry, or a 409 that means something different in sandbox than in live traffic.
When OakCore opens an API Integration Consulting engagement, the first workshop often frustrates product managers — we spend more time on failure modes than on the demo path. That is deliberate.
What belongs on the wall early
- Which errors are retryable, and with what backoff
- How idempotency keys travel across your service and the partner
- What “partial success” looks like for batch endpoints
- Who is paged when a dead-letter queue grows for thirty minutes
Teams that skip this work still ship. They also ship tribal knowledge. Six months later a new engineer “improves” retries and doubles customer charges.
A practical sequence
Inventory the partner’s documented errors. Add the undocumented ones your logs already show. Map each to an owner action: retry, surface to the user, or open a ticket with the vendor. Only then polish the happy-path sequence diagram.
If you want a second set of eyes on an existing integration, an Integration Audit is usually enough — you do not always need a full multi-week programme.