Field notes
Setting timeout budgets for partner APIs you do not control
When a third-party API is slow, your timeout policy decides whether users wait, fail fast, or retry into a worse outage.
Partner APIs sit outside your release process, yet they sit inside your user journeys. A generous timeout feels polite until threads pile up; a harsh timeout feels aggressive until you realise it protects the rest of the stack.
Build a budget from the outside in. Decide the maximum wait a user or upstream job can tolerate for the whole journey, then allocate slices to each external call. Leave a residual for your own processing — otherwise the last hop always inherits the leftover scraps.
Document what happens when the budget expires. Silent hangs are worse than a clear fallback. Whether you show a delayed confirmation, queue for later, or offer a manual path, the behaviour should be intentional and tested.
Retries belong in the same conversation. Blind retries against a saturated partner multiply load. Prefer bounded retries with jitter, and only on errors that are safe to repeat. Idempotency keys turn this from theory into practice.
During an Integration Latency Audit we often find timeouts copied from an old sample client rather than derived from journey budgets. Rewriting those numbers is usually cheaper than adding more capacity.