Handle limits and errors
Know when to correct an input, wait and retry, or check workspace access.
Request sizes and pacing
| Limit | Value |
|---|---|
| JSON body | At most 1 MiB |
| Profiles per import | 1–100; report creation allows 0–100 |
| List page | Default 50, maximum 100 |
| Read requests per minute | Default 60 per key / 300 per workspace |
| Write requests per minute | Default 10 per key / 50 per workspace |
| Submitted profile rows per minute | Default 1,000 per workspace; shared by creation and imports |
Request ceilings are operational defaults and can vary by workspace. Validation previews count toward admission limits. On 429, wait for the response’s Retry-After delay before retrying. Use backoff with jitter for transient failures; retain the same idempotency key for writes.
Common responses
| HTTP | Meaning | Next action |
|---|---|---|
| 400 | Invalid query, cursor, JSON or retry key | Correct the request; keep collection filters unchanged when paging |
| 401 | Missing, invalid or inactive key | Check the credential and environment |
| 403 | Operation is not permitted | Check scopes and current issuer/workspace access |
| 404 | Resource is unavailable to this caller | Check the report/receipt/run ID and workspace |
| 405 | Unsupported method | Use the method in the reference |
| 409 | Retry content conflict, identity conflict or archived report | Read error.code and correct the cause |
| 410 | Receipt has expired | Reconcile the report before starting new work |
| 413 / 415 | Body too large / wrong content type | Reduce the batch / send application/json |
| 422 | Invalid report or profile batch | Correct the input; import error.details identifies rows |
| 429 | Admission limit reached | Respect Retry-After |
| 500 / 503 | Temporary failure or API access paused/unavailable | Retry transient failures with backoff; check workspace access if persistent |
Keep the request ID
Responses include request_id and the matching X-Request-ID header. Errors include error.code and a readable message. Share the request ID when requesting help; do not share your API secret. Validation errors additionally include safe row/field details.
{
"error": {
"code": "unauthorized",
"message": "A valid credential is required."
},
"request_id": "77777777-7777-4777-8777-777777777777"
}HTTP success and scan success
A 201 import can be followed by a failed scan. Customer usage displays request success separately from scan outcomes. A pause on new API work does not cancel work already admitted or disable ordinary product access.