Skip to main content
Idempotência é a propriedade que garante que executar a mesma operação N vezes produz o mesmo efeito que executar uma única vez. É essencial para integrações robustas que precisam fazer retry em caso de timeout, queda de conexão ou erro 5xx. A API Pontua não oferece um header Idempotency-Key server-side hoje. As recomendações abaixo são boas práticas client-side que evitam duplicação no seu lado.

Quando importa

Operações que mudam estado (POST/PATCH/DELETE) e podem causar dano se duplicadas. Exemplos típicos:
  • Criar colaborador duplicado (CPF idêntico)
  • Registrar batida duplicada
  • Disparar geração de relatório 2x e gastar processamento à toa
GET é naturalmente idempotente (não muda estado).

Padrão: chaves naturais

Quando o recurso tem uma chave única natural, use ela para verificar se já existe antes de criar.

Exemplo: Colaborador (chave natural = CPF)

Ao retentar essa função, ela não duplica — porque a primeira coisa que faz é checar se o CPF já existe.

Padrão: tabela de intenção no cliente

Quando não há chave natural óbvia (ex.: criar registro de ponto pode ser ambíguo), persiste a intenção antes de enviar:

Backoff exponencial em retries

Quando precisar retentar (timeout, 5xx), espere progressivamente:

Veja também

  • Erros — quais status codes são retriables
  • Rate Limits — boas práticas de throttling