> For the complete documentation index, see [llms.txt](https://docs.visualsentinel.com/llms.txt)

# Errors

A failed request returns an HTTP status code. Most error bodies use the ErrorResponse shape below: a readable message and, where the endpoint sets one, a stable machine-readable code to branch on.

## ErrorResponse fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | string | No | Readable message. |
| `code` | string | No | Stable machine-readable code when the endpoint sets one, for example `SCOPE_DENIED`, `REGION_UNAVAILABLE` or `LOCATION_RESTRICTED`. |
| `message` | string | No |   |
| `details` | any | No | Validation details when available. |

Model page: [ErrorResponse](https://docs.visualsentinel.com/reference/models/error-response.md).

## Status codes

- `400`: The request failed validation. The body says what to fix, often with a code.
- `401`: Credentials are missing, invalid or expired. Send an API key or sign in again.
- `402`: The workspace plan, trial or account state does not allow this action.
- `403`: The credentials work but are not allowed to do this: a missing scope, a role, a plan restriction or a session-only endpoint.
- `404`: The resource does not exist, or your workspace cannot see it.
- `409`: The request conflicts with the current state of the resource.
- `410`: The endpoint or resource was retired. The description names the replacement where there is one.
- `422`: The request was understood, but the target could not be processed.
- `429`: Too many requests. Wait before retrying, for the seconds in `Retry-After` where the response sends it.
- `500`: The request failed on our side. Retry later.
- `502`: A service the endpoint depends on did not answer. Retry later.
- `503`: The service is temporarily unavailable. Retry later.

## Error codes

Codes the reference documents, with the status codes they come with. The endpoint pages show which responses mention each code.

- `API_ACCESS_NOT_IN_PLAN`: `403`
- `ASSERTIONS_CHANGED`: `409`
- `BASELINE_FILE_NOT_FOUND`: `400`
- `DEPENDENCY_EXISTS`: `409`
- `FEATURE_RESTRICTED`: `403`
- `INVALID_API_CONFIG`: `400`
- `INVALID_ASSERTION_PATTERN`: `400`
- `INVALID_KEYWORD_CONFIG`: `400`
- `INVALID_LOCATION`: `400`
- `LIMIT_EXCEEDED`: `403`
- `LOCATION_RESTRICTED`: `403`
- `LOCATION_UNSUPPORTED_FOR_TYPE`: `400`
- `NOT_AN_ALERT`: `400`
- `PAGE_NOT_TESTABLE`: `503`
- `PLAN_LIMIT_EXCEEDED`: `403`
- `RATE_LIMIT`: `429`
- `REGION_UNAVAILABLE`: `400`
- `SCOPE_DENIED`: `403`
- `SEAT_PAUSED_BY_PLAN`: `403`
- `SESSION_REQUIRED`: `401`, `403`
- `SPEED_TEST_FAILED`: `503`
- `SPEED_TEST_SERVICE_BUSY`: `503`
- `SPEED_TEST_UNAVAILABLE`: `503`
- `SUBPAGE_NOT_ON_PLAN`: `409`
- `UNSUPPORTED_FIELD`: `400`
- `VISUAL_DISABLED`: `409`
- `VISUAL_TARGET_NOT_READY`: `409`
- `VISUAL_VIEWPORT_LIMIT`: `403`

Repeated `429` answers mean the client is over a limit, see [Rate limits](https://docs.visualsentinel.com/guides/rate-limits.md). Scope and plan errors are explained in [Authentication](https://docs.visualsentinel.com/guides/authentication.md).