Erros - VMArea Developer Docs

Envelope de resposta

Todas as respostas da API compartilham uma estrutura de envelope comum. Sucesso:

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

pagination está presente apenas em endpoints de listagem. Erro:

{
  "success": false,
  "error": "Mensagem de erro legível",
  "details": [ ... ]
}

details está presente apenas quando o erro é uma falha de validação (veja abaixo).

Códigos de status HTTP

Status	Significado
`400 Bad Request`	O corpo da requisição ou os parâmetros de query falharam na validação, ou uma regra de negócio foi violada (ex.: limite de recursos excedido).
`401 Unauthorized`	Nenhum token fornecido, ou o token é inválido, expirado ou revogado.
`403 Forbidden`	O token é válido, mas não possui o escopo necessário, ou você está tentando acessar um recurso que pertence a outro usuário.
`404 Not Found`	O recurso solicitado não existe, ou pertence a outro usuário e não está visível para você.
`409 Conflict`	A operação conflita com o estado atual do recurso (ex.: criar um recurso com nome duplicado, ou acionar uma ação em uma VM que já tem uma em andamento).
`422 Unprocessable Entity`	A requisição é estruturalmente válida, mas semanticamente rejeitada (ex.: combinação de template de SO / plano não suportada).
`429 Too Many Requests`	Limite de taxa excedido. Veja Limites de taxa.
`500 Internal Server Error`	Ocorreu um erro inesperado no servidor. Se persistir, entre em contato com o suporte.
`502 Bad Gateway`	A plataforma não conseguiu alcançar a infraestrutura subjacente para esta operação. Tente novamente após um curto intervalo.

Estrutura do erro de validação

Quando a validação da requisição falha (status 400), o campo details contém um array de erros Zod:

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

Cada item em details segue o schema de erros do Zod: code, path, message e campos adicionais dependendo do tipo de erro.