⚠️ Tratamento de Erros

A API retorna erros em formato padronizado:

{
  "code": "error_code",
  "message": "Mensagem de erro legível",
  "details": {}, // Opcional: detalhes adicionais
  "request_id": "uuid" // ID único da requisição para rastreamento
}

Códigos de Status HTTP

  • 200 OK - Sucesso
  • 201 Created - Recurso criado com sucesso
  • 204 No Content - Sucesso sem conteúdo (DELETE)
  • 400 Bad Request - Dados inválidos ou validação falhou
  • 401 Unauthorized - Não autenticado ou token inválido
  • 403 Forbidden - Sem permissão para acessar o recurso
  • 404 Not Found - Recurso não encontrado
  • 409 Conflict - Conflito (ex: idempotência)
  • 500 Internal Server Error - Erro interno do servidor

Códigos de Erro Comuns

  • validation_error - Erro de validação de dados
  • unauthorized - Não autenticado
  • invalid_token - Token inválido ou expirado
  • not_found - Recurso não encontrado
  • database_error - Erro na base de dados
  • invalid_credentials - Credenciais inválidas
  • missing_signature - Assinatura ausente (webhooks)
  • invalid_signature - Assinatura inválida (webhooks)
  • idempotency_replayed - Evento já processado

Exemplo de Resposta de Erro

{
  "code": "validation_error",
  "message": "Dados inválidos",
  "details": {
    "issues": [
      {
        "path": ["email"],
        "reason": "Email inválido"
      }
    ]
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}