Rate limits and errors

How rate limits work

Every limit counts requests in a fixed window of 60 seconds. A counter starts with the first request and resets 60 seconds later. Every API server shares the same counters, so spreading requests over servers does not raise a limit.

A route counts against two kinds of limits:

• Per caller: one counter per API key or per signed-in user.
• Per IP address: one counter per client IP, whatever key or token it sends.

A request has to stay under both. The IP limit is counted first, so a client over its IP limit does not use up any key's budget.

Limits per route

All values are requests per 60 seconds.

The last two rows are one budget per caller across all routes. A secret key that uploads documents, polls tasks and reads mappings spends 1200 requests per minute in total, not 1200 on each route. Search, suggest and /mcp have their own counters and do not spend that budget.

Plan limits are separate from rate limits. The monthly searches of your plan are counted for billing and warn you at 80% and 100%, but they never block a search. Plans and billing lists the limits of each plan.

When you hit a limit

A request over a limit answers 429 with a Retry-After header. The header holds the number of seconds until the counter resets.

HTTP/1.1 429 Too Many Requests
Retry-After: 23
Content-Type: application/json

{"error": {"code": "RATE_LIMITED", "message": "Too many requests, retry later", "details": []}}

Wait for the seconds in Retry-After, then send the request again. Do not retry right away. Every rejected request still counts against the IP limit of the current window.

Stay under the limits

• Batch your documents. One upload takes up to 1000 documents. A catalog of 50,000 products is 50 requests, not 50,000.
• Poll tasks slowly. Check a task every second or two, not in a tight loop.
• Wait for a pause before you suggest. Send the suggest request when the shopper stops typing for about 150 ms, not on every key press.
• Count shoppers behind your server. When your storefront server calls search for every shopper, they all share your server's key and IP. 600 searches per minute is 10 per second. Cache popular results on your server if you need more.

The error format

Every error answers with the same JSON body:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed",
    "details": [{ "path": "allowedOrigins.0", "message": "expected scheme://host[:port], optionally *.host" }]
  }
}

• code is stable. Branch on it in your code.
• message is for people. It may change, so do not parse it.
• details lists the fields that failed, each with a path and a message. It is empty for errors that are not about one field.

Error codes

Ids of another organization's projects, indices or keys answer 404, the same as ids that do not exist. So a 403 FORBIDDEN means the resource exists and you may see it, but your role or your key may not do this to it.

Bad request (400)

Unauthorized (401)

Forbidden (403)

Not found (404)

The resource does not exist or belongs to another organization. The code names what was not found: ORG_NOT_FOUND, PROJECT_NOT_FOUND, INDEX_NOT_FOUND, DOCUMENT_NOT_FOUND, TASK_NOT_FOUND, PROFILE_NOT_FOUND, SUGGEST_NOT_FOUND, SUGGESTION_NOT_FOUND, SYNONYM_NOT_FOUND, RULE_NOT_FOUND, API_KEY_NOT_FOUND, MEMBER_NOT_FOUND, USER_NOT_FOUND, SESSION_NOT_FOUND. A route that does not exist answers NOT_FOUND.

Conflict (409)

Other statuses

Related

• API keys
• Organizations, members and roles
• Integrate a storefront