Reference

Rate limits and retries

Back off safely without creating duplicate records or retry storms.

Do not assume one fixed quota

Controls may differ by endpoint and environment. When Concierge returns rate-limit headers, use those values instead of a hard-coded request rate.

Header	Use
RateLimit-Limit	Maximum requests in the current policy window
RateLimit-Remaining	Requests remaining before throttling
RateLimit-Reset	When the policy window resets
Retry-After	Minimum delay before retrying a 429

Retry only safe work

Reads can usually be retried. Mutations require a stable idempotency identity or a reconciliation check first.

Keep the same idempotency and delivery identity across transport retries.
Cap attempts and elapsed time.
Do not retry 400, 401, 403, or 404 unchanged.
Use one retry owner so queues, workers, and HTTP clients do not all retry independently.

delay = min(maxDelay, baseDelay * 2 ** attempt) + randomJitter

if status === 429:
  wait(max(retryAfter, delay))
if status >= 500 and operationIsIdempotent:
  wait(delay)
otherwise:
  stop and surface the failure

Next guide

Security checklist