Establish idempotency and retry logic for flaky APIs

Provides technical rules, backoff schedules, and idempotency key designs to safely retry failed API requests without duplicate records.

You getStatus Code Strategy, backoff Schedule & Jitter Formula and idempotency Key Specification

Prompt

Prompt
Act as a backend automation architect. Define a production-grade retry and idempotency policy for external HTTP API requests that experience transient rate limits and network drops.

Rules:
- Provide a clear exponential backoff schedule with jitter to avoid thundering herd issues.
- Specify exact HTTP status codes that must be retried versus codes that must fail immediately.
- Define how to construct and send an idempotency key to prevent duplicate creation on mutations.
- Detail an automated dead-letter queue (DLQ) procedure for persistent failures.

Output format:
1. Status Code Strategy (table: HTTP Code, Retry Action, Reason)
2. Backoff Schedule & Jitter Formula
3. Idempotency Key Specification (generation method, header naming, expiration window)
4. Dead-Letter Queue Policy
5. Pre-deployment Verification Checklist

Example output

1. Status Code Strategy
HTTP CodeRetry ActionReason
429 Too Many RequestsRetryRate limit hit; inspect 'Retry-After' header first
500 Internal Server ErrorRetryUpstream transient server glitch
502 / 503 / 504RetryGateway timeout or transient connection drop
400 Bad RequestDo Not RetryPayload malformed; retry will fail identically
401 / 403Do Not RetryAuth failure; requires credential refresh or permissions
404 Not FoundDo Not RetryResource missing; retrying will not resolve
2. Backoff Schedule & Jitter Formula

Apply exponential backoff with full jitter to avoid simultaneous retries:

  • Base delay: 2 seconds
  • Max retry attempts: 4
  • Formula: Sleep = Random_Between(0, Min(Max_Delay, Base * (2 ^ Attempt_Count)))
  • Sequence ceiling: Attempt 1 (~1-2s), Attempt 2 (~2-4s), Attempt 3 (~4-8s), Attempt 4 (~8-16s).
3. Idempotency Key Specification
  • Key generation: Combine tenant ID, event type, and unique source record ID hashed with SHA-256 (e.g., hash(order_123_create)).
  • Header: Send as Idempotency-Key: [hash_value].
  • Expiration window: Enforce 24-hour persistence on the receiving cache to safely cover all delayed retry attempts.
4. Dead-Letter Queue Policy
  • After 4 failed attempts, push original payload, request headers, error stack, and timestamp to a dead-letter queue (DLQ).
  • Alert on-call via automated operational webhook if DLQ depth exceeds 10 records within 15 minutes.
  • Store payloads with a 7-day retention period for safe replay after root-cause mitigation.
5. Pre-deployment Verification Checklist
  • Confirm remote endpoint documentation explicitly supports the Idempotency-Key header on POST/PUT requests.
  • Verify test suite simulates network drops without creating secondary duplicate database entries.
  • Confirm DLQ replay runner preserves initial timestamps for accurate reporting.
Written by AI from this prompt. Your results will vary.

Use this prompt directly in ChatGPT, Claude, or Gemini when planning backend integrations. As a next step, ask the model to generate the exact retry wrapper logic in Node.js, Python, or your platform of choice.

Make it repeatable

Keep using this prompt without pasting it in every time.

Keep exploring

More in Automation & Workflows