Errors and rate limits

All errors follow a consistent JSON format. HTTP status codes indicate the error category.

Error response format

json

{
  "detail": "Human-readable error description",
  "code": "machine_readable_code",
  "field": "field_name_if_applicable"
}

HTTP status codes

200OKRequest succeeded.

201CreatedResource created successfully.

400Bad RequestInvalid request parameters or body.

401UnauthorizedMissing, expired, or invalid authentication token.

403ForbiddenAuthenticated but not permitted to access this resource.

404Not FoundResource does not exist or is not accessible in your workspace.

409ConflictResource already exists (e.g., duplicate connection alias).

422Unprocessable EntityRequest schema validation failed. Check field errors.

429Too Many RequestsRate limit exceeded. Back off and retry.

500Internal Server ErrorUnexpected server error. Contact support if persistent.

Rate limits

All endpoints120 req/min per workspace

POST /scans10 req/min per workspace

POST /auth/login20 req/min per IP

Rate limit headers are returned on every response:

http

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1713000060

Retry guidance

For 429 errors, wait until X-RateLimit-Reset then retry. Use exponential backoff for 500 errors:

python

import time, requests

def api_call_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.get(url, headers=headers)
        if resp.status_code == 429:
            reset = int(resp.headers.get("X-RateLimit-Reset", time.time() + 60))
            time.sleep(max(0, reset - time.time()))
            continue
        if resp.status_code >= 500:
            time.sleep(2 ** attempt)
            continue
        return resp
    raise Exception("Max retries exceeded")

Pagination

List endpoints support limit and offset query parameters:

bash

GET /findings?limit=50&offset=100&severity=high

json

{
  "total": 342,
  "findings": [ ... ],
  "limit": 50,
  "offset": 100
}