An SDK may automatically retry requests that are safe or idempotent, such as GET, PUT and DELETE, after a connection failure or a 503. It should not replay a POST unless the API gives it a way to detect duplicates, and it should wait as long as the server's Retry-After header says.
Why retry defaults are a security and safety question
A retry loop looks like a pure reliability feature. In practice it decides whether a customer is charged twice, whether an account gets created twice, and whether your API gets hammered during an outage. Because the SDK ships to many applications, a bad default repeats in all of them.
RFC 9110 defines an idempotent method as one where multiple identical requests have the same intended effect as a single one. It lists PUT, DELETE and the safe methods as idempotent. It also says a client should not automatically retry a request with a non-idempotent method unless it knows the request is actually idempotent or can detect that the original was never applied.
A simple retry policy table
| Request type | Retry after network error? | Retry after 429 or 503? |
|---|---|---|
| GET, HEAD | Yes, with backoff | Yes, honor Retry-After |
| PUT, DELETE | Yes, with backoff | Yes, honor Retry-After |
| POST without a duplicate guard | No, surface the error | Only if the server says the request was not processed |
| POST with an idempotency key | Yes, reuse the same key | Yes, reuse the same key |
The last row only works if your API supports it. An idempotency key is a client generated value the server stores, so a repeated request returns the first result instead of acting twice. The HTTP RFC does not define such a header, so if you add one, document its exact behavior, how long keys are remembered, and what happens when the same key arrives with a different body.
Steps to set safe retry defaults
- Classify every endpoint in your SDK as safe, idempotent or neither. Keep the list in code, next to the method definition, so it cannot drift.
- Set a small default retry count, with exponential backoff and random jitter, so thousands of clients do not retry in step.
- Parse Retry-After. RFC 9110 says the value is either an HTTP date or a number of seconds, so your parser needs both forms.
- Cap the total time spent retrying. A retry loop with no ceiling turns a short outage into a hung application.
- Make retries visible. Log the attempt number and the reason, without logging credentials or request bodies, and expose a hook so callers can turn retries off.
- Test the failure cases: connection reset after the request is sent, timeout before any response, and a 503 with each Retry-After form.
Common mistakes
Retrying on every error status is the usual one. A 400 or 403 will fail the same way each time, and repeating it only adds load and noise to your logs. Another is retrying a request after the body stream was consumed, which silently sends an empty or truncated body the second time.
A third mistake is forgetting that retries multiply other limits. If your SDK retries three times and the application also retries three times around the SDK call, one user action can produce sixteen requests. Document where retries live so teams do not stack them.
Finally, treat the retry setting as part of the public interface. Changing the default count or the set of retried methods in a minor release can change behavior for every customer, so list it in the changelog.
Quick check
Can an SDK retry a POST safely?
Only if the server can recognise a repeated request, for example through an idempotency key you define and document, or if the server states the request was not processed. Otherwise surface the error to the caller.
What does Retry-After contain?
Either a number of seconds to wait or an HTTP date, according to RFC 9110. Your SDK should accept both.
If you want a record of which SDK versions and libraries your customers' builds depend on, Safeguard's SBOM and dependency scanning can inventory them, and you can try the free scan.
Sources
Last reviewed: 19 October 2026.
