Idempotência & Infraestrutura

Cabeçalho de Idempotência (Idempotency-Key)

Idempotency-Key: e8a78c1b-4f9e-4c08-9df8-2e06c7e3f89a

Como a KavroPay Trata Chaves Idempotentes

1. Primeira Requisição: O servidor processa a criação da cobrança ou do saque normalmente e armazena o resultado em memória rápida (Redis) com TTL de 24 horas indexado pela chave. O cálculo interno do hash de idempotência utiliza o valor normalizado em centavos (amountCents), prevenindo ambiguidades entre strings decimais em Reais e centavos.
2. Requisição Repetida: Caso sua aplicação envie a mesma Idempotency-Key com o mesmo payload, a KavroPay detecta a chave existente e devolve imediatamente a mesma resposta anterior, sem criar uma nova transação no banco de dados e sem acionar o adquirente novamente.

Limites de Taxa (Rate Limiting)

• Limite Padrão: 120 requisições por minuto por API Key.
• Consultas Leves de Status (/v1/status): Otimizadas para respostas de até 10ms via cache em memória.

Cabeçalhos de Resposta de Rate Limit

Resposta de Limite Excedido (HTTP 429)

{
  "statusCode": 429,
  "message": "Too Many Requests. Limite de requisições excedido.",
  "error": "Too Many Requests",
  "timestamp": "2026-09-28T12:00:00.000Z",
  "path": "/v1/charges"
}

Roteamento Inteligente & Failover Adquirente

• Circuit Breaker Automático: Detecta anomalias no adquirente primário e chaveia o fluxo automaticamente para adquirentes secundários sem intervenção manual.
• Zero Downtime: Sua integração não é interrompida por manutenções de gateways específicos.

Recomendações de Timeout do Cliente

Estatísticas Públicas da Plataforma

• GET https://api.kavropay.com.br/v1/public-stats (aliases /public-stats e /public/stats)
• Cota de 40 requisições por minuto por IP com cache Redis de 30 segundos.

{
  "usersCount": 477,
  "transactionsCount": 2109,
  "volumeMoved": 95289.96,
  "withdrawalsCount": 175,
  "medWonCount": 37,
  "medResolvedCount": 39,
  "updatedAt": "2026-11-13T23:50:00.000-03:00"
}