RELIABILITY DESK / PROTOCOLS04 NOTES
Patterns that hold up
under real traffic.
Retry policy, idempotency, pagination, and error shape are architecture decisions, not implementation details.
What this section covers
Most integration outages are not caused by a single wrong line. They are caused by a retry loop with no cap that turns a provider hiccup into a self-inflicted storm, by a POST retried without an idempotency key that charges a customer twice, or by offset pagination silently skipping rows while the underlying table changes.
These notes describe the pattern, the failure mode it prevents, the boundary conditions where it stops working, and the primary standard or provider documentation behind each rule.
API reliability protocols
API retries: exponential backoff, jitter, caps, and stop conditions
Design an API retry policy that respects Retry-After, avoids synchronized retry storms, limits total latency, and separates safe from unsafe methods.
- exponential backoff
- full jitter
- retry budget
Idempotent POST requests: prevent duplicate payments, orders, and jobs
Implement idempotent API writes with durable operation keys, atomic storage, input fingerprints, in-flight states, and retained results.
- idempotent POST
- duplicate charge
- operation key
API pagination: offset vs cursor under changing data
Choose offset, page, keyset, or cursor pagination based on data churn, stable ordering, random access, caching, and client recovery requirements.
- offset pagination
- cursor pagination
- duplicate records between pages
RFC 9457 Problem Details: a useful API error response format
Design application/problem+json responses with stable types, status, title, detail, instance, extensions, and safe machine-readable field errors.
- application/problem+json
- type title status detail instance
- RFC 9457
RELATED WORKBENCHES02
Reproduce it locally.
These tools take the same evidence the notes above describe and compute the result in your browser tab.
Section FAQ
Before you dig in
How many retries is the right number?
Bound the total latency budget, not the attempt count. Three to five attempts with exponential backoff, full jitter, and a hard cap on cumulative wait is typical; always honour Retry-After when the server sends it, and never retry a non-idempotent write without an idempotency key.
Should new APIs adopt RFC 9457 problem details?
For new surfaces, yes: a machine-readable type, title, status, detail, and instance give clients something stable to branch on. For an existing API, add the format alongside the current shape rather than replacing it in place.
CONTINUERELATED SECTIONS
Rate budget, authentication challenge, cache validator, and CORS policy all arrive as header fields.
Open section →Error deskAPI error indexStatus codes are the first branch. Provider codes, headers, and request state narrow the repair.
Open section →Workbench indexAll six APITC toolsDecode, simulate, analyse, plan, diff, and compile — locally.
Open section →