Why is documenting an API's failure and retry semantics more important than documenting its success behaviour?

What is being tested

Whether you see documentation as a resilience mechanism rather than as a supporting artefact.

The reasoning

The success path is discoverable. An integrator makes a call, sees a response, and builds against it. Nothing in the documentation is load-bearing for behaviour they can observe directly.

The failure path is not discoverable, because it does not happen during development. The integrator never sees a timeout, a duplicate delivery, an out-of-order event, or a rate limit in their first week. So they build against the model they assume, and their assumption is always the most convenient one: exactly-once delivery, ordered events, requests that either succeed or fail cleanly.

Every one of those assumptions is wrong, and each produces a specific production bug — double fulfilment, a state machine that breaks on an out-of-order refund, a retry loop that makes an incident worse.

What must be documented explicitly

• Idempotency. Which operations are idempotent, how keys are supplied, how long they are retained, and what happens on a replay with different parameters.
• Delivery semantics. "Webhooks are delivered at least once; you must deduplicate on event ID." Stated plainly, not implied.
• Ordering. "Events may arrive out of order; fetch the object's current state rather than deriving it from the event sequence."
• Retry schedule and terminal state. How many attempts, over what period, and what happens afterwards.
• Rate limits, including the response and the recommended client behaviour.
• Timeout semantics. What a timeout means about whether the operation occurred — the single most consequential question and the one most often unanswered.

The industry benchmark

Stripe's documentation is widely treated as the reference standard, and the reason is precisely this: it documents the failure and retry model with the same care as the happy path. Idempotency keys, at-least-once webhook delivery, out-of-order arrival and reconciliation are presented as first-class parts of the interface rather than as caveats.

That is a design decision as much as a writing one. Because the API's dominant driver is correctness under retry, the provider's careful guarantees are defeated by a consumer who assumed exactly-once and shipped a double-fulfilment bug. The provider's correctness depends on the consumer's understanding, which makes the documentation part of the mechanism.

The economic argument, if the writing argument does not land

Every ambiguity becomes support tickets, forever, from every integrator who hits it. Documenting the failure model once is cheaper than answering questions about it for the life of the product — and far cheaper than the incident where a partner double-charged customers because your delivery guarantee was implied rather than stated.