Errors and rate limits
Defined API JSON errors use {"error":{"code":"…","message":"…"}}. Branch on code, rather than message text.
| code | HTTP | Action |
|---|---|---|
UNAUTHORIZED | 401 | Bearer token missing, malformed, suspended, revoked or expired. Check the token. |
INSUFFICIENT_SCOPE | 403 | This endpoint requires audit:read (audit log API) or reports:read (evaluation results API). Use a token issued in Settings → Plans and API. |
PLAN_NOT_ELIGIBLE | 403 | The organization does not have an effective Business or MSP plan. |
IP_DENIED | 403 | The source IP is outside the organization allowlist. Connect from an allowed network. |
INVALID_PARAMETER | 400 | Unknown or duplicate query parameter. |
INVALID_LIMIT | 400 | limit is not an integer within the allowed range. |
INVALID_TIME | 400 | Invalid timestamp format/date, or since is later than until. |
INVALID_CURSOR | 400 | Invalid, modified or cross-organization cursor. Restart from the saved time window. |
NOT_FOUND | 404 | Evaluation results API only. The report does not exist or belongs to another organization. |
RATE_LIMITED | 429 | Wait the number of seconds in Retry-After, then retry the same request. |
Rate limits
The audit log and evaluation results APIs share 60 requests per minute per token and 120 requests per minute per source IP before authentication. The IP check runs after Bearer format validation but before database token lookup. Collectors sharing an egress address share that IP allowance.
Exceeding either application limit returns HTTP 429 and Retry-After in seconds. Wait and retry the same page. Do not advance the checkpoint on an error. Treat transport failures and non-JSON responses as failures too.
The front-end web server also limits /api/v1/ to 120 requests per minute per source IP, allowing bursts of up to 20 requests. Its 429 returns the same JSON body as an application 429 and includes Retry-After. The body does not identify which layer responded, and you do not need to distinguish them. In either case, wait the number of seconds in Retry-After, then retry the same request.