Erros

A Simplafy Seguros API retorna erros em um formato consistente, padronizado por um exception filter global (AllExceptionsFilter). Toda resposta de erro carrega o status HTTP, uma mensagem sanitizada, o caminho da requisição e um timestamp ISO 8601.

Formato canônico

Todas as respostas de erro seguem a mesma estrutura JSON:

{
  "statusCode": 400,
  "message": "Bad Request - Invalid parameters",
  "timestamp": "2026-05-29T14:23:11.482Z",
  "path": "/api/policies"
}

Em ambiente de desenvolvimento, dois campos adicionais aparecem:

{
  "statusCode": 500,
  "message": "Internal Server Error - Please try again later",
  "timestamp": "2026-05-29T14:23:11.482Z",
  "path": "/api/policies",
  "error": "QueryFailedError: column \"foo\" does not exist",
  "stack": "QueryFailedError: ..."
}

Campos

Erros de validação

Erros de validação (DTO via class-validator) chegam ao filtro como BadRequestException com message em formato de array de strings. O array é preservado em errorDetails.validationErrors no log de auditoria interno e, em desenvolvimento, retornado integralmente na resposta.

{
  "statusCode": 400,
  "message": "Bad Request - Invalid parameters",
  "timestamp": "2026-05-29T14:23:11.482Z",
  "path": "/api/sells",
  "error": [
    "value must be a positive number",
    "source should not be empty"
  ]
}

Correlação por request ID

A API correlaciona requisições e erros via header x-request-id. Se o cliente envia esse header, o filtro de exceções atualiza o log de evento de API correspondente (criado pelo ApiLoggingInterceptor) com os detalhes do erro. Recomendado enviar um UUID por requisição para facilitar suporte e debugging.

curl https://api-seguros.simplafy.com.br/api/policies \
  -H "x-api-key: $SIMPLAFY_API_KEY" \
  -H "x-request-id: $(uuidgen)"

Códigos HTTP

O filtro global mapeia o status HTTP para uma mensagem sanitizada em produção. A tabela abaixo lista os códigos com tratamento explícito.

Outros códigos HTTP retornados por exceções específicas (ex.: 503 em manutenção) caem no caso default e recebem a mensagem genérica de 500.

Autenticação dupla (JWT + API key)

A API aceita duas formas de autenticação no mesmo guard (JwtOrApiKeyGuard):

• JWT em cookie httpOnly — usado pelo frontend autenticado.
• API key no header x-api-key — usado por integrações server-to-server.

Quando ambas falham, a resposta é 401. A ordem de avaliação é jwt primeiro, depois api-key; uma API key inválida não bloqueia o fallback para JWT.

Códigos internos

O campo errorCode é registrado no log interno (api_event_logs.errorDetails.errorCode) e ajuda no diagnóstico. Ele não é exposto na resposta HTTP por padrão, mas pode ser obtido via suporte ou via endpoints administrativos.

Erros de banco e infraestrutura

Erros vindos do driver ou do TypeORM passam por um mapeamento de mensagens genéricas antes de chegar ao cliente, evitando vazamento de schema:

Códigos brutos do PostgreSQL mais relevantes para idempotência e validação:

export const POSTGRES_ERROR_CODES = {
  UNIQUE_VIOLATION: '23505',
  NOT_NULL_VIOLATION: '23502',
};

Esses códigos são usados internamente para converter conflitos de unicidade em 409 Conflict e violações de NOT NULL em 400 Bad Request.

Como tratar

const response = await fetch(url, options);
if (!response.ok) {
  const body = await response.json();
  switch (body.statusCode) {
    case 401:
      return redirectToLogin();
    case 403:
      return showForbidden();
    case 429:
      return scheduleRetry(body);
    default:
      return reportError(body);
  }
}

const requestId = crypto.randomUUID();
const response = await fetch(url, {
  headers: {
    'x-api-key': process.env.SIMPLAFY_API_KEY,
    'x-request-id': requestId,
  },
});
// Guarde requestId junto com seus logs locais.