Why is retrying a timed-out POST request different from retrying a GET request?
Quick answer
A timed-out GET can generally be retried because GET is idempotent: repeating it is not meant to add another effect. A POST is not guaranteed to be idempotent, so the server may have completed an action—such as creating a resource—even if you never received its response. Before repeating a POST, check that API’s documentation for an idempotency mechanism or a way to confirm the original outcome. [S1][S2]
The question, the details, the next step.
Why is it riskier to retry a timed-out POST than a timed-out GET? If my client got no response, doesn't that mean the request failed?
No response tells you that the client did not receive a response; by itself, it does not tell you whether the server carried out the request. The server may have acted before the connection timed out. [S1][S2]
GET is idempotent, meaning repeating the request is not intended to add another effect. POST is not guaranteed to be idempotent: repeating it can create an additional resource or otherwise repeat an action. [S1]
So treat a timed-out GET and POST differently. A GET is generally suitable for retrying, subject to the API’s documented guidance. For a POST, first look for the API’s documented retry and idempotency behavior, or determine whether the original action was applied. A timeout alone is not proof either way.
What should I look for in the API documentation before retrying?
Check the documentation for the specific endpoint and operation, not just a general statement that the service supports retries. Look for:
- Whether the endpoint supports an idempotency mechanism, such as a documented
Idempotency-Keyheader. [S1] - How that mechanism is meant to be used for repeated attempts. Follow the API’s stated rules; do not assume support or behavior from the header’s name alone. [S1]
- What the API says to do after a timeout, including any documented way to check whether the original operation completed.
- Any endpoint-specific retry limits or conditions.
An API may document a mechanism to make a POST safe to repeat, but support and behavior for a particular endpoint must come from that API’s documentation. [S1][S2]
Can you show me how to decide in a realistic case, without assuming a particular API?
Suppose an application sends a POST intended to create an order, then times out before receiving a response. Whether an order was created is unknown: the timeout does not establish that the server did or did not complete the work. [S2]
Use this decision path:
- Pause automatic repeats of that POST while the outcome is unclear.
- Check the endpoint documentation for a supported idempotency mechanism and its instructions. If the API documents a way to make repetition safe, follow those instructions for the retry. [S1][S2]
- If no such mechanism is documented, check whether the API documents a way to inspect the operation’s outcome. Use that information to avoid repeating an action that may already have been applied.
- If you cannot establish the outcome and the API provides no documented safe retry method, do not treat retrying as risk-free. Consult the API’s documentation or support for the appropriate next step.
This is a decision guide, not a guarantee that a particular order API has an outcome lookup or an idempotency feature.
What if the client library automatically retries requests, or the documentation is unclear?
Check the client library’s retry settings and the API’s guidance together. Do not assume an automatic retry is safe for POST just because it is built into a library: POST is not guaranteed to be idempotent, and a timed-out request may already have taken effect. [S1][S2]
If the documentation is unclear, avoid enabling repeated POST attempts until you can confirm the endpoint’s supported behavior. Ask the API provider which retry conditions apply and how to determine the original operation’s outcome.
A practical rule: retry a POST only when the API documents a safe repetition method or you know the original was not applied. [S2]
A practical checklist
Identify the exact POST endpoint and the action it may perform.
Treat a timeout as an unknown outcome, not proof that the action failed. [S2]
Check endpoint documentation for an idempotency mechanism and its required behavior. [S1]
Look for a documented way to confirm whether the original operation completed.
Retry only when the documented method makes repetition safe or you know the original was not applied. [S2]
Review client-library automatic retries before allowing them to repeat POST requests.
A few more useful answers
Does a timeout mean the POST request failed?
No. A timeout does not establish whether the server completed the work; the request may have taken effect even though the client received no response. [S2]
Is every POST unsafe to retry?
Not necessarily. An API may document an idempotency mechanism that makes a POST safe to repeat, but support and behavior depend on that API’s documentation. [S1]
Can I assume an API supports `Idempotency-Key`?
No. Check the specific API’s documentation for support and instructions; the existence of the header does not establish that a particular endpoint uses it. [S1]
Sources
References used for this guide.
- [S1] Idempotency-Key header — HTTP | MDN developer.mozilla.org · Checked
- [S2] 500, 502, 503, and 504 errors from APIs: what they mean and how to handle them learn.microsoft.com · Checked