Idempotência

// A chave de idempotência transforma "cobrar" em "garantir que foi cobrado".
interface Resultado {
  status: number;
  corpo: unknown;
}

// chave -> resultado da primeira execução (Redis/tabela com UNIQUE na vida real)
const executadas = new Map<string, Resultado>();

async function criarPagamento(chave: string, valor: number): Promise<Resultado> {
  // 1. Já vi essa chave? Devolve O MESMO resultado, sem executar de novo.
  const anterior = executadas.get(chave);
  if (anterior) return anterior;

  // 2. Inédita: executa e guarda o resultado ANTES de responder.
  //    Em produção, o "guardar" precisa ser atômico (INSERT com UNIQUE):
  //    duas chamadas simultâneas com a mesma chave não podem passar juntas.
  const cobranca = { id: crypto.randomUUID(), valor, status: "paga" };
  const resultado: Resultado = { status: 201, corpo: cobranca };
  executadas.set(chave, resultado);
  return resultado;
}

// O cliente gera UMA chave por operação e a repete em todo retry:
const chave = "pedido-8231-pagamento"; // derivada da operação, não do request
await criarPagamento(chave, 100); // executa e cobra
await criarPagamento(chave, 100); // timeout? retry? -> mesmo resultado, R$100 uma vez

import uuid

# chave -> resultado (na vida real: tabela com UNIQUE ou SET NX no Redis)
executadas: dict[str, dict] = {}

def criar_pagamento(chave: str, valor: int) -> dict:
    # repetiu a chave? devolve o mesmo resultado, sem cobrar de novo
    if chave in executadas:
        return executadas[chave]

    cobranca = {"id": str(uuid.uuid4()), "valor": valor, "status": "paga"}
    resultado = {"status": 201, "corpo": cobranca}
    executadas[chave] = resultado
    return resultado

chave = "pedido-8231-pagamento"  # uma chave POR OPERACAO, repetida no retry
criar_pagamento(chave, 100)  # cobra
criar_pagamento(chave, 100)  # retry apos timeout -> mesma resposta, sem duplicar