Rate limits

The v2 API enforces rate limits per team. Before a request is authenticated (when the key can’t yet be resolved to a team), the limiter falls back to per-IP.

Response headers

Most v2 API responses, whether 2xx or not, carry three headers. The unauthenticated /v2/openapi.json document is an exception.

Header	Meaning
`X-RateLimit-Limit`	The window’s total budget.
`X-RateLimit-Remaining`	How many requests you have left in the current window.
`X-RateLimit-Reset`	Seconds until the window resets and the budget refills.

Use X-RateLimit-Remaining to pace yourself proactively — dropping to 0 triggers 429 on the next call.

Handling `429`

When you exceed the budget, v2 answers 429 Too Many Requests with the shared error envelope and a Retry-After: <seconds> header:

HTTP/1.1 429 Too Many Requests
X-Request-Id: req_01J9C2VZH8...
Retry-After: 5
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 5

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 5 seconds."
  },
  "requestId": "req_01J9C2VZH8..."
}

Wait at least Retry-After seconds before retrying. In practice, back off exponentially with jitter and cap the wait at a few minutes.

async function fetchWithBackoff(input: RequestInfo, init: RequestInit) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch(input, init);
    if (res.status !== 429) return res;
    const retryAfter = Number(res.headers.get("Retry-After") ?? "1");
    const jitter = Math.random() * 250;
    await new Promise((r) => setTimeout(r, retryAfter * 1000 + jitter));
  }
  throw new Error("Rate-limited after 5 attempts");
}

/v2/openapi.json is not rate-limited — the OpenAPI document is static and safe to fetch freely.

API Reference

API v2

Surveys

Responses

Tags

Traits

Playbooks

Projects

Media

Response headers

Handling `429`

​Response headers

​Handling 429

Response headers

Handling `429`