{
    "api": "YAML JSON TOON Database",
    "version": "1.0.0",
    "format": "json",
    "dataset": {
        "id": 1003,
        "slug": "http-request-retry-decisions",
        "title": "HTTP Retry Decision Reference",
        "description": "Failure scenarios and retry decisions for HTTP clients, including idempotency, backoff, deadlines, and ambiguous writes.",
        "summary": "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_when": [
            "Implement a client that survives transient failures.",
            "Distinguish safe retries from duplicated writes."
        ],
        "caveats": [
            "Status alone cannot prove a write was not applied.",
            "An idempotency key works only if the server defines and enforces it."
        ],
        "related": [
            "http-server-error-guide",
            "http-conditional-requests"
        ],
        "category": "HTTP Status Codes",
        "category_slug": "http-status-codes",
        "tags": "http-status-codes,http request retry decisions,reference,engineering",
        "view_count": 0,
        "created_at": 1791798640,
        "updated_at": 1791798640,
        "reviewed_at": "2026-10-12",
        "sources": [
            {
                "title": "IETF HTTP semantics",
                "url": "https://httpwg.org/specs/rfc9110.html"
            },
            {
                "title": "AWS retry and jitter guidance",
                "url": "https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/"
            }
        ],
        "reading": [
            "api-retries-with-backoff-and-idempotency"
        ],
        "provenance": "Original editorial reference notes by YJTOON, informed by the linked primary documentation. External specifications retain their own licenses.",
        "entry_count": 12,
        "fields": [
            {
                "section": "data",
                "field": "scenario",
                "type": "string",
                "example": "GET times out"
            },
            {
                "section": "data",
                "field": "decision",
                "type": "string",
                "example": "Usually retry within a budget"
            },
            {
                "section": "data",
                "field": "action",
                "type": "string",
                "example": "Back off with jitter and a total deadline."
            },
            {
                "section": "data",
                "field": "risk",
                "type": "string",
                "example": "Repeated attempts still increase server load."
            }
        ]
    },
    "data": [
        {
            "scenario": "GET times out",
            "decision": "Usually retry within a budget",
            "action": "Back off with jitter and a total deadline.",
            "risk": "Repeated attempts still increase server load."
        },
        {
            "scenario": "POST times out after sending",
            "decision": "Do not blindly retry",
            "action": "Reconcile by operation ID or use documented idempotency support.",
            "risk": "The server may have committed the first request."
        },
        {
            "scenario": "429 Too Many Requests",
            "decision": "Retry only after waiting",
            "action": "Honor Retry-After and cap the attempt count.",
            "risk": "Immediate retries amplify throttling."
        },
        {
            "scenario": "503 Service Unavailable",
            "decision": "Potentially retry",
            "action": "Respect Retry-After when present and use jitter.",
            "risk": "A prolonged outage can exhaust client resources."
        },
        {
            "scenario": "502 Bad Gateway",
            "decision": "Potentially retry",
            "action": "Retry only when the operation is safe to repeat.",
            "risk": "The upstream may already have processed a write."
        },
        {
            "scenario": "400 Bad Request",
            "decision": "Fix the request",
            "action": "Inspect validation errors and send a corrected request.",
            "risk": "Repeating identical input wastes the budget."
        },
        {
            "scenario": "401 Unauthorized",
            "decision": "Refresh credentials if supported",
            "action": "Refresh once, then fail clearly if still unauthorized.",
            "risk": "An unbounded refresh loop hides real auth problems."
        },
        {
            "scenario": "403 Forbidden",
            "decision": "Do not automatically retry",
            "action": "Check the policy and caller permissions.",
            "risk": "New attempts do not grant authorization."
        },
        {
            "scenario": "404 Not Found",
            "decision": "Usually stop",
            "action": "Check the identifier; retry only for documented eventual creation.",
            "risk": "A missing resource is not a transient transport failure."
        },
        {
            "scenario": "409 Conflict",
            "decision": "Reconcile first",
            "action": "Reload state and apply the domain-specific conflict policy.",
            "risk": "Blind retries can repeat a logically invalid operation."
        },
        {
            "scenario": "412 Precondition Failed",
            "decision": "Reload and reconsider",
            "action": "Fetch the new revision before attempting an edit.",
            "risk": "Replacing the validator defeats concurrency protection."
        },
        {
            "scenario": "Connection refused",
            "decision": "Bounded retry if appropriate",
            "action": "Use a small retry budget and report the endpoint.",
            "risk": "Permanent configuration errors do not heal with backoff."
        }
    ]
}