Rate limits and retries

​

The rate-limit response

{
  "error": {
    "message": "Rate limit exceeded.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "param": null
  }
}

• Retry-After — a server-provided backoff hint.
• Rate-limit headers — available quota or window information when exposed by the deployment.
• X-Request-ID — a correlation ID for tracing.

​

Recommended backoff

1. If Retry-After is present, wait at least that long.
2. Otherwise use bounded exponential backoff, such as 1, 2, 4, 8 seconds.
3. Add random jitter to each delay.
4. Stop after a small number of attempts and return a recoverable error to your caller.

async function waitForRetry(attempt, retryAfterSeconds) {
  const serverDelay = Number(retryAfterSeconds);
  const baseDelay = Number.isFinite(serverDelay)
    ? serverDelay * 1000
    : Math.min(8000, 1000 * 2 ** attempt);
  const jitter = Math.floor(Math.random() * 250);
  await new Promise((resolve) => setTimeout(resolve, baseDelay + jitter));
}

​

Avoid retry storms

• Limit concurrent requests in your worker pool.
• Apply backoff per operation, not once globally for all traffic.
• Do not retry a malformed request or invalid credentials.
• Prefer a queue for bursty workloads.
• Record retry count and final status for monitoring.

​

Idempotency note