Rate limits

​

Budgets

• “Concurrent” counts in-flight HTTP requests, not active runs. POST /v1/runs responds in milliseconds, so this limit rarely matters. POST /v1/go/run (synchronous) holds a slot for the entire search. Active runs have a separate cap: see Runs per organization.
• Apart from these limits, at most 5 Go jobs (POST /v1/go/runs) can be running at once per user: a sixth returns 429 too_many_runs with Retry-After: 30.
• Failed authentication is limited per IP address. See Failed authentication.

​

Failed authentication

• A 401 or 403 response to a request whose Authorization header holds a key that Retriever knew as active, for example a key revoked a moment ago.
• A 401 or 403 response to a request that sends a session cookie that is not valid.
• A 401 from the Unipile webhook to a request that sends a Unipile signature or auth header.
• Any response that is not 2xx from an /oauth/ endpoint, for example an invalid authorization code (400) or an authorization request from a browser that is not signed in (302). A signed-in browser on /oauth/authorize does not count. These failures use a separate budget, so they do not block /mcp or /v1.

​

MCP

• Each JSON-RPC message sent to /mcp counts as one request on the key’s mcp budget. This budget has the same size as reads: by default, 600 MCP messages per minute per key.
• The API calls that a tool makes count in their own classes, like the same calls made over REST. For example, service_execute counts one mcp message and one services request for POST /services/{serviceName}. The JSON-RPC message itself does not count in reads. The API calls a tool makes do count, so a key used for both MCP and REST shares its reads, services and heavy budgets between them.
• A JSON-RPC batch (several messages in one HTTP request; most clients never send one) holds at most 10 messages, and each message counts. A larger batch gets 400 with JSON-RPC error -32600 before any message runs. This does not limit service_batch_execute, which takes 1 to 100 inputs.
• A body larger than 10 MiB gets 413 with JSON-RPC error -32600. A body that is not valid JSON gets 400 with JSON-RPC error -32700.
• On /mcp, a spent budget is an HTTP 429 with the body above and Retry-After, not a JSON-RPC error.
• An MCP request with a valid key never adds a failure to the per-IP budget. The API calls that a tool makes are not checked against it.

​

Runs per organization

• Runs started with POST /v1/runs and with the MCP tool retriever_build_list_start share the same slots.
• A further run is accepted with 202 and stays queued while all the slots are taken: by runs of your organization that are running or recovering, or by its older queued runs, which start first. Its queue field says why it waits and how many older runs of your organization wait before it (ahead). Read it on GET /v1/runs/{id}.
• It starts on its own when one of them ends. Do not create it again.
• Runs of other organizations are not delayed by yours.
• Go jobs (/v1/go/runs) and conversations run from the app do not use these slots.

​

Request size

{ "error": { "code": "body_too_large", "message": "The request body exceeds the 10 MiB limit (10485760 bytes)." } }

{ "jsonrpc": "2.0", "id": null, "error": { "code": -32600, "message": "The request body exceeds the 10 MiB limit (10485760 bytes).", "data": { "code": "body_too_large" } } }

​

Headers

RateLimit-Limit: 600
RateLimit-Remaining: 587
RateLimit-Reset: 42

​

429 response

{ "error": { "code": "rate_limited", "message": "Rate limit exceeded. Retry in 12 s." } }

{ "error": { "code": "rate_limited", "message": "Too many requests. Retry in 7 s." } }

{ "error": "rate_limited", "error_description": "Too many requests. Retry in 7 s." }