Skip to main content

Rate limits

Learn how many requests you can send to the Onna API and how to recover when you exceed a limit.

Limits​

Unless an endpoint lists its own limit below, requests share a budget of 600 requests per minute for each access token. Requests without a token aren't rate limited; they're rejected with 401. Legal Hold (/legalhold/*) endpoints are not covered by these limits.

POST /oauth/token has its own limit of 30 requests per minute for each client_id. Failed attempts count toward it. Reuse an access token until it expires instead of requesting a new one for each call.

POST /search has its own limit of 300 requests per minute for each access token.

GET /accounts/metrics has its own limit of 60 requests per minute for each access token.

POST /exports has its own limit of 10 requests per minute for each access token. Each export is a long-running job, so poll GET /exports/{onna_id} for its status instead of creating it again.

POST /search-term-reports/{report_id}/run has its own limit of 10 requests per minute for each access token. A report also runs at most once every 10 minutes, and a start inside that window gets the same 429 and Retry-After. Poll the run with GET /search-term-reports/{report_id}/runs/{run_id} instead of starting it again.

Rate-limited responses​

When you exceed a limit, the API responds with 429 Too Many Requests and a Retry-After header that gives the number of seconds to wait before calling again:

HTTP/1.1 429 Too Many Requests
Retry-After: 17
Content-Type: application/json
X-Correlation-ID: 0b6c2a53-5f1e-4a8e-9a57-3c8a2f6d1e44

{
  "code": "00429_too_many_requests",
  "id": "0b6c2a53-5f1e-4a8e-9a57-3c8a2f6d1e44",
  "title": "Too Many Requests",
  "detail": "Too many requests: wait the number of seconds given in the Retry-After header, then retry",
  "links": {"about": "https://dev.onna.com/fundamentals/response-codes#4XX"},
  "source": null
}

The id in an error body matches the X-Correlation-ID response header. Quote it when you contact support about a failed request.

Best practices​

Wait for the Retry-After delay before retrying, and spread bulk work over time instead of sending it in bursts.

For the full list of status codes, see Response codes.

Last updated on