Rate limits

Rate limiting is one of several independent controls that protect the API. It caps how fast you can call the API — a latency and cost safeguard that stops one caller degrading the service for everyone and bounds the blast radius of a runaway or leaked key. It does not cap how much data you can extract in total; that is the job of the pagination depth cap. Two layers enforce it, split by what each layer can distinguish:

Cloudflare edge — per-IP limits on anonymous, unauthenticated traffic, applied before the request reaches the API.
In-API per-key floor — a per-API-key limit of 5 requests per second by default, applied to requests authenticated with an API key. The floor is overridable per key; paid plans can raise it.

The two layers stack. The edge bounds anonymous bursts by IP; the in-API floor bounds a single API key regardless of source IP, because the edge sees a token but cannot resolve it to a key or plan. Only API-key (machine-to-machine) requests are subject to the per-key floor — interactive, logged-in app sessions are not.

When you exceed the limit

The API returns 429 Too Many Requests. Which layer rejected the request determines the body:

In-API floor (per key) — the standard error envelope, with the stable RATE_LIMITED code:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests"
  }
}

Cloudflare edge (per IP) — a Cloudflare-generated payload, not the API error envelope, because the request never reaches the API server.

Detect rate limiting by HTTP status code, not by body shape — that works for both layers:

if (response.status === 429) {
  // Rate limited — back off and retry
}

Response headers

A 429 carries a Retry-After header — the number of seconds to wait before retrying. Honor it.

Header	Description
`Retry-After`	Seconds to wait before retrying — present on `429` responses

The API does not emit X-RateLimit-Limit, X-RateLimit-Remaining, or X-RateLimit-Reset headers. The per-key limiter runs independently on each API replica with no shared counter, so a precise remaining-budget cannot be reported. Pace requests against your known floor and treat a 429 as the authoritative signal.

Handling 429 in your client

Use exponential backoff. If Retry-After is present, honor it instead of a fixed delay.

async function withRetry<T>(fn: () => Promise<T>, maxAttempts = 5): Promise<T> {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err: any) {
      if (err.response?.status !== 429 || attempt === maxAttempts) throw err;
      const retryAfter = Number(err.response.headers["retry-after"]);
      const delayMs = Number.isFinite(retryAfter)
        ? retryAfter * 1000
        : Math.min(2 ** attempt * 1000, 30000);
      await new Promise(r => setTimeout(r, delayMs));
    }
  }
  throw new Error("unreachable");
}

Best practices

Batch where possible. Use aggregate endpoints instead of fetching individual entities to compute totals.
Cache responses. Most reference data (taxonomy, dimensions) changes rarely — cache for the lifetime of your app’s request cycle.
Use one API key per integration. Sharing a key across services makes the per-key floor harder to reason about — every service draws from the same budget.
Coalesce parallel calls. If your dashboard fires 8 parallel aggregate calls per page load, that’s 8 against the floor. Fan-out is fine; storms aren’t.

Requesting a higher limit

If your workload needs sustained higher throughput (data pipelines, periodic exports, research workloads), contact your Dealroom account manager to raise your key’s floor. Include:

The use case and expected request volume (peak and sustained requests per second)
Which endpoints will see the most traffic
Whether the work can run off-peak

Programmatic data exports are usually better served by the aggregate endpoints or a custom bulk-export arrangement than by raising raw request limits.

Getting Started

Examples

Concepts

References

Agent APIs

When you exceed the limit

Response headers

Handling 429 in your client

Best practices

Requesting a higher limit

​When you exceed the limit

​Response headers

​Handling 429 in your client

​Best practices

​Requesting a higher limit

When you exceed the limit

Response headers

Handling 429 in your client

Best practices

Requesting a higher limit