api: YAML JSON TOON Database
version: 1.0.0
format: yaml
dataset:
  id: 1588
  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
  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.
  category: HTTP Status Codes
  category_slug: http-status-codes
  tags: http-status-codes,http request retry decisions,reference,engineering
  view_count: 8
  created_at: 1791798640
  updated_at: 1791798640
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.