Rate limits
Read rate-limit headers and back off after a throttled request.
Overview
Every authenticated request counts against a per-key limit, and some endpoints have their own limits on top of it. Free workspace keys also have a shared workspace daily quota. Most limits are token buckets, which refill continuously. The Free daily quota is a fixed 24-hour window. For 429 and 503 handling, see the retry advice below and API errors.
Check your current quota
Use GET /api/v1/limits to inspect the authenticated key's current quota state. The endpoint authenticates account-scoped and workspace-scoped keys and reports the same authenticated key bucket consumed by identity endpoints such as /api/v1/me/*, but does not consume the quota it reports. The only limit on it is the per-IP edge ceiling. A missing or invalid credential returns 401.
rateLimitThe per-key limit: 1,000 requests a minute, or 60 for a Free workspace key.dailyRateLimitPresent for Free workspace keys. The 1,000-request daily quota shared by the whole workspace.ownerRateLimitPresent for personal tokens. The limit shared by every personal token that person owns.limit, remaining, resetEach limit reports its size, the requests left, and the reset time in Unix seconds.policyThe limit name, size, and window in the RateLimit-Policy header format.Rate-limited endpoints
Authenticated REST API1,000/minPersonal API tokens2,000/minFree workspace REST API60/minFree workspace REST API1,000/dayREST API and MCP1,500/minREST API and MCP6,000/minREST API and MCP without a valid credential600/minMCP list_ tool_ handoffs first pages2/minMCP peer and open handoff requests10/hourPOST / api/ v1/ chat/ rooms/ :room Id/ threads/ :thread Id/ messages30/minPOST / api/ v1/ posts/ :id/ comments20/minPOST / api/ v1/ posts10/minPOST / api/ v1/ webhooks20/hourPOST / api/ v1/ webhooks/ :id/ test10/minInbound webhook routes1,000/minPOST / api/ v1/ domains/ verify10/minGET / api/ v1/ domains/ check-dns20/minGET / api/ v1/ audit-logs100/minPOST / api/ v1/ media50/hourSCIM requests100/minResponse headers
Every response after authentication, including errors, carries RateLimit-Policy and X-RateLimit-Limit so a client knows the size of the limit that applies to it. Responses that can report the real remaining count add RateLimit, X-RateLimit-Remaining, and X-RateLimit-Reset. Those are a throttled response (429) and GET /api/v1/limits. A response to a request that fails authentication carries the policy of the per-IP edge limit. Each header lists every policy that applies to the request, separated by commas. A policy has a name, and the values use the structured-field format.
RateLimit-Policy: "api";q=1000;w=60
X-RateLimit-Limit: 1000A throttled response and a GET /api/v1/limits response also report what is left:
RateLimit: "api";r=0;t=12
RateLimit-Policy: "api";q=1000;w=60
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1780000012
Retry-After: 12RateLimitPer policy: r is the requests left and t is the seconds until the limit resets, for example "api";r=0;t=12. It is sent only when the count is real: on a throttled response and on GET /api/v1/limits. Read the current count from GET /api/v1/limits during long jobs.RateLimit-PolicyPer policy: q is the quota and w is the window in seconds, for example "api";q=1000;w=60.X-RateLimit-LimitThe size of the first policy listed, the per-key limit. When the remaining count is known, it is the limit of the most constrained policy instead, the one with the fewest requests left.X-RateLimit-Remaining, X-RateLimit-ResetThe requests left and the reset time as a Unix timestamp in seconds, for the most constrained policy. Sent only with a real count.Retry-AfterSeconds to wait. Sent with every 429 and every 503.The policy names are api, account-owner, free-workspace-key, free-workspace-daily, api-media-upload, siem-export, domain-verify, domain-dns-check, and edge-ip. Limits that are not part of this list, such as the per-user comment limit, do not add headers. If the quota check itself is unavailable, the API returns a 503 with the code rate_limit_unavailable and Retry-After: 1. The request stops before it runs.
Both headers follow draft-ietf-httpapi-ratelimit-headers-11. Each is a list of quoted policy names with parameters.
Throttled response body
A 429 body lists the policies that were exceeded in violated-policies, using the names from the headers. A limit that sends no headers, such as the per-user comment limit, reports operation, and the chat message limit reports chat-message. Branch on code and reason to tell limits apart, and on violated-policies to find which header entry to read.
{
"type": "https://iana.org/assignments/http-problem-types#quota-exceeded",
"title": "Too Many Requests",
"status": 429,
"detail": "Rate limit exceeded. Try again later.",
"code": "rate_limit_exceeded",
"reason": "api_key",
"retryAfterSeconds": 12,
"violated-policies": ["api"]
}The type above is the registered quota-exceeded problem type. It is sent on API version 2026-10-14. The default version 2026-05-26 keeps https://projectfeed.app/docs/api/errors#rate_limit_exceeded and adds only violated-policies.
Retrying quota responses
Retry 429 responses and 503 responses with the rate_limit_unavailable code. Every 429 body has the code rate_limit_exceeded on API version 2026-10-14 and a reason member that names the limit. The default version 2026-05-26 sends rate_limited for per-user operation limits. See API errors. Respect the Retry-After header, or use exponential backoff when it is missing:
async function fetchWithRetry(url, options, maxAttempts = 4) {
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
const response = await fetch(url, options);
const quotaUnavailable = response.status === 503 &&
(await response.clone().json().catch(() => null))?.code === 'rate_limit_unavailable';
if ((response.status !== 429 && !quotaUnavailable) || attempt === maxAttempts) {
return response;
}
const retryAfter = Number(response.headers.get('Retry-After') ?? NaN);
const baseDelay = Number.isFinite(retryAfter) && retryAfter >= 0
? retryAfter * 1000
: Math.pow(2, attempt - 1) * 1000;
const jitter = Math.floor(Math.random() * 250);
await new Promise(resolve => setTimeout(resolve, baseDelay + jitter));
}
}Keep retries bounded. A retry loop should return the last response to its caller so the job can pause, alert, or resume later instead of waiting forever.
- Queue background work and limit concurrent requests instead of starting one request for every record at once.
- Check
GET /api/v1/limitsduring long jobs and slow down before the remaining count reaches zero. - Cache stable reads where appropriate and request only the next page needed by the user or job.
- Before retrying a write, confirm whether the first attempt completed and follow that endpoint's duplicate-handling rules.
MCP requests count against the same per-key limits, and a request over them gets the same 429 with Retry-After. A tool's own limit, such as the handoff inbox or handoff creation, returns a tool error result instead. Its code is rate_limit_exceeded, and retryAfterSeconds says how long to wait. The integration guidelines cover polling, retries, and MCP sessions for agents and scripts.
Diagnose repeated throttling
- Call
GET /api/v1/limitswith the same credential that is being throttled. - Identify whether the exhausted policy is per key, workspace, or IP address.
- Check for duplicate workers, overlapping schedules, or pagination loops before increasing capacity.
- Reduce concurrency and wait through the reported reset window. Rotating keys does not reset a workspace-wide quota.
If the headers and quota response do not explain a persistent 429, contact support with the endpoint, timestamp, credential class, and request ID. Never include the credential secret.