Ir para o conteúdo

Tratamento de Erros

Todos os erros das APIs Rock Conecta seguem o padrão RFC 9457 (Problem Details), com Content-Type: application/problem+json (ou application/json em alguns casos de tenant).

Estrutura comum

Campo Tipo Descrição
type string Slug identificador do tipo de erro
title string Título legível
status integer HTTP status code
detail string Descrição detalhada
instance string URI do endpoint que gerou o erro
timestamp string (ISO 8601) Data/hora do erro
correlationId string Do header X-Correlation-Id ou gerado
sessionId string SessionId do request (null se indisponível)
traceId string ID de rastreamento
errors array Lista de erros de validação (apenas em 400)
errors[].type string REQUIRED_FIELD, INVALID_FORMAT ou INVALID_DOCUMENT
errors[].field string Campo com erro
errors[].message string Mensagem descritiva

Exemplos

{
  "type": "validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request contains invalid fields",
  "instance": "/api/v1/tenants/{tenantId}/customers/identify",
  "timestamp": "2026-06-10T19:00:00.000Z",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "sessionId": null,
  "traceId": "abc123",
  "errors": [
    { "type": "REQUIRED_FIELD", "field": "sessionId", "message": "Field sessionId is required." }
  ]
}

{
  "type": "tenant-not-found",
  "title": "Tenant Not Found",
  "status": 404,
  "detail": "Tenant not found",
  "instance": "/api/v1/tenants/{tenantId}/discounts/authorizations",
  "timestamp": "2026-06-10T19:00:00.000Z",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "sessionId": null,
  "traceId": "abc123"
}

Tenant inexistente x inativo

Por segurança, tenant inexistente e tenant inativo retornam a mesma resposta 404 — não é possível descobrir se um tenant existe pela resposta de erro.

Status codes por operação

HTTP Ocorre em Significado
400 Todas Erro de validação (campos, formato, documento inválido)
401 Todas Credenciais inválidas ou ausentes
404 Todas Tenant não encontrado/inativo; ou loja não encontrada (registrar venda)
422 Registrar venda Divergência entre total dos itens e valor da venda
500 Identificar cliente Erro interno inesperado
503 Autorizar descontos / Registrar venda Banco do tenant indisponível ou recurso desativado

Recomendações de tratamento

Retry com backoff

  • Faça retry com backoff exponencial apenas para erros 5xx e 503.
  • Não faça retry automático de 400, 401 e 404 — são erros de request que não se resolvem sozinhos.
  • Sempre envie o header X-Correlation-Id (UUID) para correlacionar a chamada com os logs da Rock Conecta em caso de suporte.
  • Registre correlationId e traceId do response de erro para facilitar a investigação.

Referências