API
Errors
One envelope, a stable set of codes, and a message you can paste into a bug report.
Every error response has the matching HTTP status and this body:
{
"error": {
"code": "invalid_request",
"message": "destination.url must be a valid URL (http or https).",
"param": "destination.url"
}
}codeis stable and meant for your code to branch on.messageis a sentence meant for a person.paramnames the request field the error is about, when there is one. Nested fields use dots (destination.url), array items use their index (rows.0.url).
Codes
| Status | code | When |
|---|---|---|
| 400 | invalid_request | The body or query failed validation, or breaks a rule (unknown folder, a scan host you do not own). param names the field. |
| 401 | invalid_api_key | The Authorization header is missing, malformed, or the key was revoked. |
| 401 | expired_api_key | The key passed its expiry date. Create a new one in Settings, Developers. |
| 403 | plan_required | The workspace's plan does not include the API or this feature (webhooks, GPS, access codes). |
| 403 | insufficient_scope | A read-only key was used on a request that changes data. |
| 403 | forbidden | A plan ceiling was reached (codes, folders, pages, bulk rows) or the action is not allowed for this workspace. |
| 404 | not_found | No resource with that id in this workspace, or no endpoint at that path. |
| 409 | conflict | The change collides with existing data, for example a folder moved inside itself. |
| 413 | payload_too_large | The request body is over the accepted size. |
| 429 | rate_limited | The per-minute budget for this key is spent. Wait for the seconds in Retry-After. |
| 500 | internal_error | Something failed on our side; the request is safe to retry. |
Retrying
429 and 500 are safe to retry; use the Retry-After header on a 429 and a short backoff on a 500. Send an Idempotency-Key on POST requests so a retry after a timeout cannot create the same code twice, see Idempotency.