Erros e Status Codes

A API da QuettaCode segue o padrão RFC 7807 (Problem Details for HTTP APIs) para retorno de erros. Isso garante que todos os erros tenham uma estrutura previsível e fácil de parsear.

Estrutura do Erro

Quando uma requisição falha, a API retorna um JSON com o seguinte formato:

{
  "type": "about:blank",
  "title": "Erro de Validação",
  "status": 400,
  "detail": "O campo 'email' é obrigatório.",
  "instance": "/api/v2/auth/login"
}

• type: Uma URI que identifica o tipo de erro (pode ser usado para linkar documentação).
• title: Um resumo curto e legível por humanos sobre o erro.
• status: O código de status HTTP (o mesmo do header).
• detail: Uma explicação detalhada específica para esta ocorrência.
• instance: A URI onde o erro ocorreu.

Códigos HTTP Comuns

Aqui estão os códigos de status mais comuns que você encontrará:

Código	Significado	Descrição
200	OK	Requisição bem sucedida.
201	Created	Recurso criado com sucesso (ex: novo usuário, envio de mensagem).
204	No Content	Sucesso, mas sem corpo de resposta (ex: delete ou update simples).
400	Bad Request	Erro de validação nos dados enviados. Verifique o payload.
401	Unauthorized	Falha na autenticação. Token inválido, expirado ou ausente.
403	Forbidden	Autenticado, mas sem permissão para este recurso (Acesso Negado).
404	Not Found	O recurso solicitado não existe (ex: ID de usuário inválido).
422	Unprocessable Entity	Dados sintaticamente corretos, mas semanticamente inválidos.
429	Too Many Requests	Você excedeu o limite de requisições (Rate Limit).
500	Internal Server Error	Erro inesperado no servidor. Contate o suporte.

Tratamento Específico

403 Forbidden (Acesso Negado)

Geralmente ocorre quando um usuário tenta acessar recursos de outro Tenant ou uma funcionalidade restrita à role ADMIN.

• Solução: Verifique as permissões do usuário ou se o ID do recurso pertence ao Tenant logado.

400 Bad Request (Validação)

Geralmente acompanhado de detalhes sobre quais campos falharam na validação.

• Exemplo:

  {
    "title": "Erro de Validação",
    "status": 400,
    "detail": "O campo 'password' deve ter no mínimo 8 caracteres."
  }