Errors - VMArea Developer Docs

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.