HTTP Retry Decision Reference

Failure scenarios and retry decisions for HTTP clients, including idempotency, backoff, deadlines, and ambiguous writes.

HTTP Status Codes
12 entries
CC0 — public domain

JSON6,020 B
YAML4,309 B · −28%
TOON3,546 B · −41%

Failure scenarios and retry decisions for HTTP clients, including idempotency, backoff, deadlines, and ambiguous writes. Each row includes a practical application and a failure to check before using it.

Use it when

Implement a client that survives transient failures.
Distinguish safe retries from duplicated writes.

Watch out for

Status alone cannot prove a write was not applied.
An idempotency key works only if the server defines and enforces it.

The data

Scenario	Decision	Action	Risk
GET times out	Usually retry within a budget	Back off with jitter and a total deadline.	Repeated attempts still increase server load.
POST times out after sending	Do not blindly retry	Reconcile by operation ID or use documented idempotency support.	The server may have committed the first request.
429 Too Many Requests	Retry only after waiting	Honor Retry-After and cap the attempt count.	Immediate retries amplify throttling.
503 Service Unavailable	Potentially retry	Respect Retry-After when present and use jitter.	A prolonged outage can exhaust client resources.
502 Bad Gateway	Potentially retry	Retry only when the operation is safe to repeat.	The upstream may already have processed a write.
400 Bad Request	Fix the request	Inspect validation errors and send a corrected request.	Repeating identical input wastes the budget.
401 Unauthorized	Refresh credentials if supported	Refresh once, then fail clearly if still unauthorized.	An unbounded refresh loop hides real auth problems.
403 Forbidden	Do not automatically retry	Check the policy and caller permissions.	New attempts do not grant authorization.
404 Not Found	Usually stop	Check the identifier; retry only for documented eventual creation.	A missing resource is not a transient transport failure.
409 Conflict	Reconcile first	Reload state and apply the domain-specific conflict policy.	Blind retries can repeat a logically invalid operation.
412 Precondition Failed	Reload and reconsider	Fetch the new revision before attempting an edit.	Replacing the validator defeats concurrency protection.
Connection refused	Bounded retry if appropriate	Use a small retry budget and report the endpoint.	Permanent configuration errors do not heal with backoff.

Fields

The shape of this dataset, read from the data itself: every column, its type and a real value. Agents can use this to plan a query without fetching the whole document.

Section	Field	Type	Example
data	`scenario`	string	GET times out
data	`decision`	string	Usually retry within a budget
data	`action`	string	Back off with jitter and a total deadline.
data	`risk`	string	Repeated attempts still increase server load.

Fetch the same bytes

The static files contain the same reference rows as the API, with no API rate limit. Live metadata, such as view counts, may differ. Use the API for content negotiation; use the static files for a cacheable snapshot.

curl "https://yjtoon.com/api/dataset/http-request-retry-decisions?format=toon"

const res = await fetch(
  "https://yjtoon.com/static-data/dataset/http-request-retry-decisions.toon"
);
const toon = await res.text();

Rate limit: 120 requests per minute per IP, no key and no signup. API reference →

Sources and editorial notes

Original editorial reference notes by YJTOON, informed by the linked primary documentation. External specifications retain their own licenses.

Editorial review: 2026-10-12. Source documents keep their own licenses.

Topics

http-status-codes
http request retry decisions
reference
engineering