> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vmarea.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> How the VMArea API signals errors: the response envelope, HTTP status codes, and validation error shape.

## Response envelope

All API responses share a common envelope structure.

**Success:**

```json theme={null}
{
  "success": true,
  "data": { },
  "pagination": { }
}
```

`pagination` is only present on list endpoints.

**Error:**

```json theme={null}
{
  "success": false,
  "error": "Human-readable error message",
  "details": [ ]
}
```

`details` is only present when the error is a validation failure (see below).

## HTTP status codes

| Status                      | Meaning                                                                                                                                                                             |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`           | The request body or query parameters failed validation, or a business rule was violated (e.g., exceeded resource limit).                                                            |
| `401 Unauthorized`          | No token provided, or the token is invalid, expired, or revoked.                                                                                                                    |
| `403 Forbidden`             | The token is valid but lacks the required scope, or you are trying to access a resource that belongs to another user.                                                               |
| `404 Not Found`             | The requested resource does not exist, or it belongs to another user and is not visible to you.                                                                                     |
| `409 Conflict`              | The operation conflicts with the current state of the resource (e.g., creating a resource with a duplicate name, or triggering an action on a VM that already has one in progress). |
| `422 Unprocessable Entity`  | The request is structurally valid but semantically rejected (e.g., an unsupported OS template / plan combination).                                                                  |
| `429 Too Many Requests`     | Rate limit exceeded. See [Rate limits](/en/rate-limits).                                                                                                                            |
| `500 Internal Server Error` | An unexpected error occurred on the server. If this persists, contact support.                                                                                                      |
| `502 Bad Gateway`           | The platform could not reach the underlying infrastructure for this operation. Retry after a short delay.                                                                           |

## Validation error shape

When request validation fails (status `400`), the `details` field contains a Zod issue array:

```json theme={null}
{
  "success": false,
  "error": "Validation error",
  "details": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "undefined",
      "path": ["name"],
      "message": "Required"
    }
  ]
}
```

Each item in `details` follows the [Zod issue schema](https://zod.dev/ERROR_HANDLING): `code`, `path`, `message`, and additional fields depending on the error code.