A capability stays maintainable only when the team can explain every state, retry, and piece of residual data—not merely show one successful run. An Idempotency-Key identifies one business intent, not a generic cache entry. Bind it to actor, endpoint, and canonical body.
An API contract includes units, defaults, idempotency, error classes, and version windows—not only field types. Clients distinguish retryable, user-action, and permanent outcomes to avoid duplicate side effects.
Questions the design must answer
Write the following choices as reviewable rules instead of scattering them across callbacks and UI conditions. Explicit rules make scaling, compatibility, and diagnosis less dependent on guesswork.
- Atomically claim a pending lease, persist status plus needed response on completion, make concurrent duplicates wait or return 409/425, and reject different payloads.
- Separate protocol facts, user intent, and automatic recovery; automation may restore facts but never overturn an explicit choice.
- Ship conservative defaults, server-side ceilings, and a rollout switch instead of trusting browser-provided numbers as resource budgets.
The delivery standard for The HTTP Idempotency-Key Contract Under Retries and Concurrency is a usable normal path, convergent failures, bounded resources, and a state users can understand. The result is a production capability that can be explained, degraded safely, and rolled back—not a demo that works once.
Edge cases are part of the feature
An abnormal path is more than an error banner. It decides how in-flight work stops, how the peer learns the outcome, what residue remains, and whether the next operation inherits it.
- Proxy retries still duplicate if clients generate a new key each attempt, while storing full responses forever expands privacy and cost.
- Fixing only the UI leaves queues, locks, or expired credentials for the next operation to inherit and fail again.
- Ideal-size tests miss large files, long sessions, and concurrency that cross hidden limits and cause cascading failure.
Prove that it works with evidence
A release gate combines deterministic regression, randomized timing, and real browser pairs. Preserve the seed and state trace from every failure as a permanent replay case.
- Test concurrency, post-commit disconnect, pending-owner crash, expiry, and body mismatch; permit one business effect with bounded recovery.
- Race refresh, cancel, timeout, and remote completion in one scheduling window; assert one terminal state and one side effect.
- Before release, record success rate, p50/p95/p99 latency, error classes, and resource high-water marks with explicit rollback thresholds.
The release standard is practical: the normal path is fast, abnormal paths converge, recovery never overrides an explicit user decision, and operators can diagnose faults from limited, privacy-safe evidence.