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:

{
  "success": true,
  "data": { },
  "pagination": { }
}

pagination is only present on list endpoints.

Error:

{
  "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.
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:

{
  "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: code, path, message, and additional fields depending on the error code.