Separate an invalid request from an uncertain result
An invalid record needs correction. A confirmed temporary failure may permit a retry. A connection timeout can leave the remote outcome unknown. Do not treat all three as the same retry button. Record the category and the evidence available before selecting a recovery action.
Read the endpoint’s idempotency contract
Where the provider supports idempotency, check the key scope, parameter rules, retention period and returned results. Stripe documents one concrete implementation, including reuse of the first result for a matching key. Its behavior is not a universal property of HTTP or a guarantee about your publishing service.
Stripe: idempotent requests ↗ — Stripe documents its own key, parameter and retention behavior. This is an example, not a promise about every API.
Keep the logical operation stable
Retain the same work identity for the same intended action and keep its payload revision visible. A newly generated key can describe a new operation rather than recovering the previous one. If the content changed, resolve whether the first operation completed before deciding how the revision should be applied. Use the actual endpoint’s update and recovery rules.
Honor limits and stop with an explainable record
Respect documented rate-limit and retry guidance. GitHub’s REST guidance illustrates using the returned headers and avoiding uncontrolled repeat requests. Define an attempt or time budget and a human recovery path. The remaining unknowns belong in the receipt, not in a success message.
GitHub: REST API best practices ↗ — Provider guidance on webhooks, response handling and rate-limit headers. Apply the destination’s documented limits.
Record the plan, version, date, input set, output, failure behavior and billing units. A workflow diagram is a design pattern, not a benchmark.
