Saltar para o conteúdo principal

​
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

StatusSignificado
400 Bad RequestO 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 UnauthorizedNenhum token fornecido, ou o token é inválido, expirado ou revogado.
403 ForbiddenO 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 FoundO recurso solicitado não existe, ou pertence a outro usuário e não está visível para você.
409 ConflictA 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 EntityA requisição é estruturalmente válida, mas semanticamente rejeitada (ex.: combinação de template de SO / plano não suportada).
429 Too Many RequestsLimite de taxa excedido. Veja Limites de taxa.
500 Internal Server ErrorOcorreu um erro inesperado no servidor. Se persistir, entre em contato com o suporte.
502 Bad GatewayA 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.