Rate limits

​

Read the current window

​

Recognize a 429

{
  "message": "Rate limit exceeded",
  "error_code": "RATE_LIMITED",
  "key_metadata": {
    "credits_consumed": 0,
    "credits_remaining": 29940
  }
}

Retry-After: 23
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1788554400

​

Retry with a limit

async function requestWithRateLimitRetry(
  input: RequestInfo,
  init: RequestInit,
  maxAttempts = 3,
) {
  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    const response = await fetch(input, init);

    if (response.status !== 429 || attempt === maxAttempts) {
      return response;
    }

    const retryAfterSeconds = Number(response.headers.get("retry-after")) || 1;
    const jitterMs = Math.floor(Math.random() * 250);
    await new Promise((resolve) =>
      setTimeout(resolve, retryAfterSeconds * 1000 + jitterMs),
    );
  }

  throw new Error("unreachable");
}

​

Reduce request volume

1. Skip duplicate calls. Cache successful results in your server or database according to the product’s freshness requirement.
2. Deduplicate concurrent work. Coalesce requests for the same normalized input into one in-flight promise or job.
3. Bound fan-out. Use a worker queue with explicit concurrency for bulk work.
4. Use batches for asynchronous volume. Batch management has a separate admission and polling bucket; processed items still consume their operation credits.
5. Degrade intentionally. Return an editable form, text fallback, cached record, or queued state when enrichment is optional.

​

Weighted endpoints

​

Separate limits

• Monitor management and history operations use their own organization-level request bucket. The scrape work performed by scheduled runs is governed by monitor limits and billing, not by the number of list or retrieve calls.
• Batch submit, list, retrieve, result, cancel, and delete operations use a separate management bucket. The pages processed by a batch still settle against work credits.
• Prefetch costs zero API credits but still uses the ordinary authenticated API rate limit.
• Logo Link image delivery has a separate quota and service path from the core API.

​

Batch API has its own bucket

​

Avoid polling bursts

• Prefer a webhook when the surface offers one.
• Otherwise, start with a slow poll interval and increase it after repeated pending responses.
• Add jitter when many jobs are started together.
• Stop polling on terminal success or failure.
• Cap total elapsed time and preserve the job ID for later recovery.

​

Test the fallback

• The code reads Retry-After case-insensitively.
• The total attempt count is bounded across SDK and application layers.
• The user sees an intentional fallback after the final attempt.
• The request is not treated as a credit charge.
• Logs contain status and rate metadata, not the API key or scraped content.

​

Next steps