Clients must handle 429 Too Many Requests. Limits may vary by environment and change over time, so do not rely on a fixed request count unless an endpoint contract states one.

  1. Spread bulk work over time instead of sending sudden bursts.
  2. Limit concurrency per worker and across the organization.
  3. Retry 429 responses with bounded exponential backoff and jitter.
  4. Honor Retry-After when the response includes it.
  5. Stop after a finite number of attempts and surface the failure.
function retryDelay(attempt: number, retryAfterSeconds?: number) {
  if (retryAfterSeconds !== undefined) return retryAfterSeconds * 1_000;

  const exponential = Math.min(30_000, 500 * 2 ** attempt);
  return exponential + Math.random() * 250;
}

Avoid synchronized retries

Jitter prevents many workers from retrying at the same time. Apply it even when all workers use the same base backoff policy.

Track response status, endpoint, attempt number, delay, and x-request-id. Never attach an API key or sensitive request body to a metric or log field.

See Errors and retries for status-code and idempotency guidance.