Response format, errors & rate limits

These conventions hold across every endpoint.

The response envelope

Successful responses are wrapped in a consistent envelope:

{
  "code": 200,
  "message": "success",
  "data": { }
}

code: the HTTP status code, mirrored in the body.
message: a short human-readable status.
data: the payload (an object, or null).

Lists

List endpoints return the page in results, alongside the total and the window you asked for:

{
  "code": 200,
  "message": "success",
  "data": {
    "results": [ ],
    "count": 128,
    "limit": 10,
    "offset": 0
  }
}

Errors

Errors use the same envelope, reduced to code and message:

{
  "code": 400,
  "message": "Invalid request body"
}

Build error handling around code and message.

Common status codes: 400 invalid request · 401 authentication failed (check you’re using Authorization: API_KEY, not Bearer) · 403 insufficient permissions or API access not enabled · 404 not found · 409 already exists · 422 the request was understood but the file isn’t in a state that can answer it (the message says what’s needed) · 429 rate limited · 500 server error · 503 something on our side is temporarily unavailable, so we couldn’t answer about your file. Retry it.

503 is the one to single out: it is the only status here that says the request was fine and the fault is ours. Treat it as retryable, not as a verdict on what you sent. An upload can answer it when we can’t classify the file because a service we depend on is down.

Pagination

List endpoints page with query parameters:

?limit=<n>&offset=<n>

limit caps the page size (default 10, maximum 100); offset skips ahead. Use the count in the list envelope to know when you’ve read everything.

Rate limits

Global: 60 requests per second per IP across the API.
Sign-in endpoints: a few requests per minute per IP. These aren’t part of the /api/v1 API you call with a key.

Poll on a sensible interval (see Analysis lifecycle & polling) rather than tight-looping, and back off on 429.

Metering & quotas

Beyond rate limits, the AI work run on your files is metered against your account in investigation units. Different operations draw down different amounts.

When you’ve spent your budget, the search call is refused with a 429, the same status as a rate limit. Read the message to tell them apart: a rate limit clears on its own and is worth retrying, an exhausted unit budget is not. How the budget works and when it resets is covered in Investigation units & quotas.