Subrequest timeout failure in Cloudflare Workers outbound fetch

Recommended Pattern: Client-Generated Idempotency Keys

The standard solution is to generate a deterministic idempotency key in the Worker and pass it to the upstream API via a custom header (typically Idempotency-Key). The upstream service must implement a persistence layer that stores the result of the first successful request keyed by this value, with a TTL covering the expected retry window.

Key Generation Strategy

Generate the key from immutable request properties so retries within the same Worker invocation produce identical keys:

• Single mutation: Hash the request payload (e.g., SHA-256 of JSON body) combined with a unique transaction identifier if available.
• Multiple mutations: Use a composite key: sha256(payload + operationType + entityId).
• Cross-invocation deduplication: Store the key in Cloudflare KV or a Durable Object with a TTL matching the upstream's idempotency window.

Worker-Side Implementation

async function fetchWithIdempotency(url, options, env) {
  const payload = options.body ? JSON.stringify(options.body) : '';
  const key = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(payload));
  const idempotencyKey = Array.from(new Uint8Array(key)).map(b => b.toString(16).padStart(2, '0')).join('');

  const headers = new Headers(options.headers);
  headers.set('Idempotency-Key', idempotencyKey);

  // Optional: check KV for prior result to avoid redundant upstream calls
  const cached = await env.IDEMPOTENCY_KV.get(idempotencyKey);
  if (cached) return new Response(cached, { headers: { 'X-Idempotency-Replay': 'true' } });

  const response = await fetch(url, { ...options, headers });

  if (response.ok) {
    const clone = response.clone();
    await env.IDEMPOTENCY_KV.put(idempotencyKey, await clone.text(), { expirationTtl: 3600 });
  }
  return response;
}

Upstream Requirements

The upstream API must:

1. Accept Idempotency-Key header
2. Atomically check for existing key before executing mutation (check-and-set)
3. Store response body + status for the key's TTL (typically 1–24 hours)
4. Return cached response on subsequent requests with same key

Retry Policy

Configure exponential backoff with jitter in the Worker. Cloudflare Workers' default fetch retry behavior does not apply to subrequest timeouts—you must implement retry logic explicitly. Limit retries to 2–3 attempts to stay within CPU time limits.

Verification Steps

1. Send two identical requests with same key to upstream; confirm only one database write occurs.
2. Simulate timeout using a mock server that delays response beyond Worker's 30s subrequest limit.
3. Inspect upstream logs: second request should show cache hit, not new mutation.

Assumptions & Uncertainty

• Assumes upstream API supports idempotency headers—verify with provider.
• Assumes Workers runtime version with crypto.subtle available (all current versions).
• KV/Durable Object storage adds latency; evaluate if single-invocation deduplication (no cross-invocation store) suffices.

One diagnostic needed: Does your upstream API already support an idempotency header, or must you implement the persistence layer yourself? This changes whether you only modify the Worker or also need upstream changes.