Erros

A API do ION Guard utiliza códigos de status HTTP padrão e retorna mensagens de erro em formato JSON consistente.

Formato de resposta de erro

Erro simples

{
  "message": "Invalid credentials."
}

Erro de validação (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["O campo email é obrigatório."],
    "password": ["A senha deve ter pelo menos 8 caracteres."]
  }
}

O campo message traz um resumo legível (normalmente a primeira mensagem de validação) e o campo errors é um objeto onde cada chave é o nome do campo e o valor é um array com todas as mensagens de erro daquele campo. Sempre baseie a exibição de erros no objeto errors, não apenas no message.

Códigos de status

Código	Significado	Quando ocorre
200	OK	Requisição bem-sucedida
201	Created	Recurso criado com sucesso
204	No Content	Operação bem-sucedida sem corpo de resposta
401	Unauthorized	Token ausente, inválido ou expirado
403	Forbidden	Usuário autenticado mas sem permissão para a ação
404	Not Found	Recurso não encontrado
422	Unprocessable Entity	Erro de validação nos dados enviados
429	Too Many Requests	Rate limit excedido — veja Rate Limiting
500	Server Error	Erro interno do servidor

Tratamento recomendado

401 — Token expirado

Quando receber 401, tente renovar o token via refresh. Se o refresh também falhar, redirecione para login.

Requisição → 401 → POST /auth/refresh → Novo token → Repetir requisição
                  → 401 no refresh → Redirecionar para login

422 — Erros de validação

Itere sobre o objeto errors para exibir mensagens específicas por campo:

const response = await fetch('/api/v1/sites', { method: 'POST', body, headers });

if (response.status === 422) {
  const { errors } = await response.json();
  // errors.name → ["O campo nome é obrigatório."]
  // errors.timezone → ["O timezone selecionado é inválido."]
}

429 — Rate limit

Aguarde o tempo indicado no header Retry-After e repita a requisição:

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  await sleep(retryAfter * 1000);
  // Repetir requisição
}

500 — Erro do servidor

Erros 500 indicam um problema no servidor. Não repita a requisição imediatamente. Se persistir, verifique os logs do servidor ou contate o suporte.