Ask what the server does with a repeat#
RFC 9110 defines an idempotent method by its intended effect on the server: several identical requests have the same effect as one. PUT and DELETE are idempotent by that definition, and POST is not, which is why urllib3's default retry policy leaves POST out of Retry.DEFAULT_ALLOWED_METHODS.
The method is only a start. A PUT whose handler appends a row is not idempotent, and a POST with an idempotency key the server deduplicates can be. Two facts decide a retry:
- Does the operation tolerate a repeat? Read the handler or the API's documentation, not the verb.
- Does the failure prove the first attempt was not applied? A refused TCP connection or a 429 proves it. A read timeout, a dropped connection after the request was sent, or a 5xx does not: the server may have committed the write and lost the response.
A non-idempotent operation can still be retried after the first kind of failure. After the second kind, a retry can duplicate the write.
A comment that found a gap in a retry rule#
In November 2026, a Backblaze B2 SDK pull request stopped replaying create-style JSON POST calls after ambiguous failures. Its changelog entry reads: "Avoid replaying create-style JSON API calls after response timeouts, connection loss, or 5xx responses, including 503." Rate limits and "proven connection-establishment failures are still retried." Pull request The new _is_unapplied_error treats a failure as unapplied when it is a 429, a connect timeout, or a connection error whose cause is urllib3's NewConnectionError or ConnectTimeoutError.
CodeRabbit found a case the rule missed: "If a proxy TCP connection is refused, urllib3 wraps NewConnectionError in ProxyError." The check returns False for it, "so a create POST now stops after its first attempt, although no request reached the server." It added: "Do not accept all proxy errors." Review comment
The claim holds. With requests 2.34.2 and urllib3 2.8.0, a POST through a proxy that refused connections raised requests.ProxyError, wrapping urllib3's ProxyError around NewConnectionError. The checks in _is_unapplied_error returned True for a direct refused connection and False for the refused proxy. The merged b2http.py at commit 177a57e never mentions proxies, so the case appears unchanged. Later commits on connection-establishment errors landed before the 20 November 2026 merge, but nothing ties them to this thread.
The comment deserved a change or a follow-up issue, and its own advice marks the limit: retry the wrapped refusal, not every proxy error, because a proxy can fail after forwarding the request. Leaving the gap open costs a visible error on a create that could have been retried, and duplicates nothing, which is why refusing ambiguous replays was the right default.
A request for idempotency that would have hidden a failure#
In September 2026, a GPUStack pull request made DELETE on a persistent volume return 409 while a GPU instance that is not itself being deleted still holds the volume. Before, the route marked the volume Deleting and accepted the request, and such a volume could never finish deleting.
Two bots asked for the same exception. gemini-code-assist wrote: "To ensure the DELETE route remains fully idempotent, we should bypass the blocking check if the persistent volume is already in the Deleting phase (pv.is_deleting())." Review comment Copilot asked to "Make the holder check conditional on the volume not already being in Deleting to preserve idempotent retries." Copilot review
The author declined: "Not applying this one. The bypass would restore the false-success semantics this PR removes", because "a volume already in Deleting while a non-Deleting holder exists is exactly the stuck case from ref #6272", so "a retried DELETE must keep failing loudly (409, naming the holder) rather than reporting acceptance again." Author's reply A round-up comment added that "Retried deletes stay idempotent wherever they could have been accepted," "because instance Deleting is sticky," and that "that path is pinned by test_redelete_deleting_volume_stays_idempotent." Round-up The pull request merged the same day without the bypass.
The dismissal holds against the diff. _ensure_delete_not_blocked raises only when some holder's phase is not Deleting, and the cited test deletes a holder-free Deleting volume again and asserts it is still Deleting. A volume in that state got there through a delete that was accepted but could never finish, so a repeat that reports acceptance would repeat a false success.
Treat backoff as a separate question#
Some comments ask only for backoff, because the code retries in a tight loop. That concerns load on the dependency, and applies even to idempotent reads. Check whether the client library already retries; many cloud SDKs do, and a second loop multiplies attempts. If the loop is yours, use capped exponential backoff with jitter, as the Amazon Builders' Library article on timeouts, retries and backoff with jitter describes, and honor Retry-After when the server sends it, as the B2 SDK does for 429.
Decide from the operation and the failure#
| What you find | Response |
|---|---|
| Not idempotent, and the code retries after a timeout, lost connection or 5xx | Change: stop retrying, or add an idempotency key the server deduplicates |
| Not idempotent, and the code refuses a retry after a failure that proves nothing was sent | Change or file an issue, as with the B2 proxy refusal |
| Idempotent by the handler's contract or a documented key | Dismiss, citing the handler or the API docs |
| The bot asks a retry to report a success the operation cannot reach | Dismiss, as in the GPUStack reply |
| A retry loop with no delay or cap, or one stacked on the library's own retries | Change: add backoff with jitter, or remove your loop |
| You cannot tell what a repeat does | Write a test that sends the request twice and inspect the stored state, as the B2 tests do with a fake server |
When the duplicate comes from a user's click, the double-submit guide covers the client side.