Can you retry a POST request after a timeout?
Can you retry a POST after a timeout? Unknown outcomes, idempotency and the limits of Stripe API v1 keys, with retry timing kept separate.
A hypothetical notes app sends a POST request to create a note. The request times out without a response arriving. Should it send the request again? To decide, first separate two questions: whether a response arrived and whether the note was created.
The response is missing, the outcome is unknown
Consider one possible sequence. The client sends the request. The server processes it and commits the database write. The response is lost on its way back. The client reports a timeout. In this example, the note already exists. If every received POST creates a note, repeating it will create another.
AWS explicitly warns that a timeout does not establish that side effects have not occurred. Therefore, “I received no response” does not mean “the operation was not executed”. That distinguishes an unknown outcome from a confirmed failure. (builder.aws.com)
What idempotency means
RFC 9110, section 9.2.2, defines idempotency by the same intended server effect from one or multiple identical requests, not identical responses. It discourages automatic non-idempotent retries without known idempotent semantics or evidence that the original request was never applied. (rfc-editor.org)
In the Amazon Builders’ Library, Malcolm Featonby describes a client-provided identifier for recognising retries. Identical parameters alone do not express intent: a client might genuinely want two identical objects. The key works through the server’s agreed behaviour, not merely because it appears in the request. (aws.amazon.com)
Stripe API v1’s specific contract
Stripe API v1 replays the saved status and body, including 500 errors. Saving requires execution to begin: validation failures and concurrent execution conflicts save nothing. Changed parameters with the same key cause an error. API v2 has different replay semantics. (docs.stripe.com)
Send Idempotency-Key from the first attempt. Stripe specifies retries with the same key and parameters within the first 24 hours. Keys may then be removed; reuse after removal can start a new request. If the outcome remains unknown, stop retrying and reconcile it. (docs.stripe.com)
When to retry is a separate question
AWS recommends bounded retries and increasing delays with an upper limit to control load. The engineering inference is separate: waiting longer does not establish whether repeating an operation is correct. (builder.aws.com)
In his explanation of jitter, Marc Brooker shows why identical delays can leave requests clustered in time. A random component spreads them out. This changes when requests are sent, not how the server recognises one operation. (aws.amazon.com)
What to clarify before automatic retries
As a paper exercise, return to the note example. Place an interruption before processing, after the write and before receipt of the response. For each case, record what the client knows, what remains unknown and which part of the API contract justifies the next action. Do not replace an unknown with an assumption.
Then add two questions to the integration review: “How will we establish the outcome when retries stop?” and “What exactly does this endpoint, in this version, guarantee for this operation?”
Sources
- RFC 9110: HTTP Semantics, section 9.2.2, Idempotent Methods: https://www.rfc-editor.org/rfc/rfc9110.html
- AWS: Timeouts, retries, and backoff with jitter: https://builder.aws.com/content/3EumjoZascWd1oZiEgL8ORlv3qE/timeouts-retries-and-backoff-with-jitter
- Stripe API: Idempotent requests: https://docs.stripe.com/api/idempotent_requests
- Stripe: Advanced error handling: https://docs.stripe.com/error-low-level
- Amazon Builders’ Library: Making retries safe with idempotent APIs: https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/
- AWS Architecture Blog: Exponential Backoff And Jitter: https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/