Skip to content

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/min
Per API key|Default limit for workspace API keys and personal tokens
Personal API tokens2,000/min
Per token owner|Shared by all of one person's personal tokens
Free workspace REST API60/min
Per API key|Applies to each workspace API key in a Free workspace
Free workspace REST API1,000/day
Per workspace|A fixed 24-hour window shared by every key in the workspace
REST API and MCP1,500/min
Per credential|Edge ceiling above the per-key limit. Its 429 carries Retry-After and RateLimit-Policy but no remaining count
REST API and MCP6,000/min
Per IP address|Edge ceiling for all credentialed requests from one address
REST API and MCP without a valid credential600/min
Per IP address|Edge ceiling for requests whose API key or token is missing, malformed, or not yet accepted by the API
MCP list_tool_handoffs first pages2/min
Per key or token and direction|Shared by every status. A refused poll returns a rate_limit_exceeded tool error with retryAfterSeconds
MCP peer and open handoff requests10/hour
Per person per workspace|Shared across that person's keys. Targeted self-handoffs use 60/hour per connection and 120/hour per owner
POST /api/v1/chat/rooms/:roomId/threads/:threadId/messages30/min
Per user|Chat messages sent through the API share the budget with messages sent in the app
POST /api/v1/posts/:id/comments20/min
Per user|Shared with comments written in the app. Its 429 uses the rate_limited code
POST /api/v1/posts10/min
Per user|Shared with posts created in the app
POST /api/v1/webhooks20/hour
Per workspace|Creating outbound webhooks
POST /api/v1/webhooks/:id/test10/min
Per workspace|Shared with POST /api/v1/webhooks/:id/deliveries/:deliveryId/retry and with tests sent from the app
Inbound webhook routes1,000/min
Per inbound secret|The same limit as an API key, counted separately for each secret. The edge ceilings do not apply to these signed routes
POST /api/v1/domains/verify10/min
Per workspace|Domain ownership verification requests
GET /api/v1/domains/check-dns20/min
Per IP address|Domain DNS record lookups
GET /api/v1/audit-logs100/min
Per API key|Audit log export
POST /api/v1/media50/hour
Per API key|Base64 media uploads. Shares the budget with POST /api/v1/media/uploads, which starts an upload. Completing or checking an upload does not use it
SCIM requests100/min
Per workspace|Returns a SCIM-formatted 429 with Retry-After. See SCIM provisioning

Response 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.

HTTP
RateLimit-Policy: "api";q=1000;w=60
X-RateLimit-Limit: 1000

A throttled response and a GET /api/v1/limits response also report what is left:

HTTP
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: 12
RateLimitPer 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.

JSON
{
  "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:

JavaScript
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/limits during 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

  1. Call GET /api/v1/limits with the same credential that is being throttled.
  2. Identify whether the exhausted policy is per key, workspace, or IP address.
  3. Check for duplicate workers, overlapping schedules, or pagination loops before increasing capacity.
  4. 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.

Image preview
100%