> ## 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.

# Erros

> Formato do envelope de resposta, códigos de status HTTP e estrutura dos erros de validação da API VMArea.

## Envelope de resposta

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

**Sucesso:**

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

`pagination` está presente apenas em endpoints de listagem.

**Erro:**

```json theme={null}
{
  "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](/pt/rate-limits).                                                                                        |
| `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:

```json theme={null}
{
  "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](https://zod.dev/ERROR_HANDLING): `code`, `path`, `message` e campos adicionais dependendo do tipo de erro.