Glossário de Códigos de Erro¶

Referência oficial dos erros da integração Nayax ↔︎ Saipos, jobs de outbox e camada HTTP/Prisma. Use isto para padronizar tratamento, observabilidade e DX.

Convenções¶

• error: título curto e traduzido.
• message: detalhe legível (pode ser oculto em produção).
• code: identificador técnico quando existir (ex.: P2002, 901).
• status: HTTP status code.
• requestId: correlação nos logs.
• timestamp: ISO UTC.

Sumário¶

• HTTP genéricos
• Prisma
• Autenticação/Parceiro (Saipos)
• Aplicação (regras/negócio)
• Jobs de Outbox
• Formato de resposta de erro
• Exemplos
• Matriz de decisões (cliente)
• Observabilidade

HTTP genéricos¶

Handler de fallback: erros sem statusCode viram 500 e ocultam message fora de NODE_ENV=development.

Prisma¶

Tratamento direto no errorHandler:

• P2002 → 409 { error: 'Conflito', message: 'Registro duplicado' }
• P2025 → 404 { error: 'Não encontrado', message: 'Registro não encontrado' }

Autenticação/Parceiro (Saipos)¶

Alguns erros do parceiro usam códigos próprios no payload:

O JobsProcessor invalida tokenCache automaticamente quando detecta 401/901/902.

Aplicação (regras/negócio)¶

Erros lançados no fluxo de ingestão e regras:

Jobs de Outbox¶

Estados e transições administrados pelo JobsProcessor (cron */20 * * * * *):

Estados¶

Política de Backoff (exponencial com jitter)¶

Reaper: jobs travados em PROCESSING além do TTL (PROCESSING_TTL_MS, default 120.000 ms) são revertidos para FAILED com agendamento do próximo run.

Formato de resposta de erro¶

HTTP (REST)¶

{
  "error": "Conflito",
  "message": "Registro duplicado",
  "code": "P2002",
  "status": 409,
  "requestId": "ac76763c9d2e",
  "timestamp": "2025-10-28T10:57:12.931Z"
}

Em desenvolvimento (NODE_ENV=development), mensagens internas podem incluir stack e detalhes adicionais.

Log estruturado do Job (falha)¶

{
  "id": "job-uuid",
  "attempts": 3,
  "nextStatus": "FAILED",
  "backoff": 300000,
  "status": 502,
  "raw": { "partnerMessage": "gateway timeout" },
  "message": "Network error"
}

Exemplos¶

1) P2002 (unicidade)¶

Entrada: criação de agendamento duplicado Saída (HTTP 409):

{
  "error": "Conflito",
  "message": "Registro duplicado",
  "code": "P2002",
  "status": 409
}

2) Duplicidade de transação Nayax (produção)¶

Saída (HTTP 400):

{
  "error": "Bad Request",
  "message": "Transação 12345 já foi processada",
  "status": 400
}

3) Duplicidade de transação Nayax (teste)¶

Saída: 200 OK e log "Ignorando duplicata" (idempotência relaxada).

4) Saipos 901/902 (auth)¶

Saída (HTTP 401):

{
  "error": "Auth inválida (Saipos)",
  "code": 901,
  "status": 401
}

Ação do worker: limpar tokenCache e reautenticar.

5) DLQ por erro 422 do parceiro¶

Transição: PROCESSING → DLQ Registro no job:

{
  "status": "DLQ",
  "lastError": {
    "msg": "Campo obrigatório ausente: cod_store",
    "status": 422,
    "data": { "error": "Unprocessable Entity" }
  }
}

Matriz de decisões (cliente)¶

Observabilidade¶

Para correlação eficiente:

• Logs estruturados contêm requestId, eventKey, job.id, status, action, attempts.
• Console hard logs no JobsProcessor (pré/envio e erro) garantem visibilidade fora do Logger.
• Campos recomendados para dashboards: taxa de DLQ, latência, tentativas médias, distribuições de status, top lastError.msg.

Anexos (trechos relevantes)¶

Filtro de erros no errorHandler¶

// Prisma
if (err.code === 'P2002') return res.status(409).json({ error: 'Conflito', message: 'Registro duplicado', code: 'P2002' });
if (err.code === 'P2025') return res.status(404).json({ error: 'Não encontrado', message: 'Registro não encontrado', code: 'P2025' });

// Custom
if (err.statusCode) return res.status(err.statusCode).json({ error: err.message });

// Genérico
return res.status(500).json({
  error: 'Erro interno do servidor',
  message: process.env.NODE_ENV === 'development' ? err.message : undefined,
});

Classificação no JobsProcessor (resumo)¶

• 400/422 → DLQ
• 401/901/902 → limpa token, re-tenta
• Demais erros → FAILED + backoff exponencial (com jitter)

Takeaway: DLQ para erros de domínio, FAILED para transitórios, idempotência rígida em produção e relaxada em teste. Ajuste, reprocessa, escala.