Stripe: Design de API e Chaves de Idempotência

Pagamentos são transações com consequências reais e assimétricas. Se você cobra um cliente duas vezes por um único pedido, você criou um problema de negócio sério — reembolsos, disputa de chargeback, erosão de confiança. Se você não cobra quando deveria, perdeu receita. O problema não é teórico: em sistemas distribuídos, a entrega de uma mensagem tem três estados possíveis — entregue, não entregue, ou desconhecido. É esse terceiro estado que mata sistemas de pagamento ingênuos.

O cenário clássico: um cliente faz uma requisição POST /charges para criar uma cobrança. A requisição chega ao servidor da Stripe, o processamento começa, a cobrança é criada na rede de cartões — e então a conexão cai antes que a resposta chegue ao cliente. O cliente recebeu um timeout. O que ele deve fazer? Se ele simplesmente retentativa a requisição, ele pode cobrar o usuário duas vezes. Se ele não retenta, pode perder a venda e deixar o usuário sem o serviço que pagou.

Esse problema é amplificado pelo contexto da Stripe: ela é uma plataforma de infraestrutura. Seus clientes são desenvolvedores e empresas construindo produtos em cima da API. Qualquer solução precisa funcionar de forma confiável e previsível para milhares de integrações diferentes, muitas escritas por engenheiros que não são especialistas em sistemas distribuídos. A solução não pode depender de o cliente fazer algo sofisticado — ela precisa ser simples de usar corretamente e difícil de usar errado.

A solução da Stripe é elegante em sua simplicidade aparente, mas há profundidade considerável nos detalhes de implementação.

O contrato básico: o cliente gera um UUID único por intenção de operação e o envia no header Idempotency-Key. Se a mesma chave for enviada novamente dentro de uma janela de 24 horas, o servidor retorna exatamente o mesmo resultado da primeira execução — sem reprocessar, sem cobrar novamente. A chave é vinculada ao par (api_key, idempotency_key), não apenas à chave de idempotência isolada, o que evita colisões entre contas diferentes.

O fluxo no servidor: ao receber uma requisição, o middleware de idempotência faz um GET atômico no Redis pela chave composta. Se encontrar um resultado completo, retorna imediatamente com o HTTP status original e o payload original — o cliente não consegue distinguir se foi a primeira execução ou uma retentativa. Se não encontrar nada, adquire um lock distribuído (via SET NX no Redis) para garantir que requisições concorrentes com a mesma chave não processem em paralelo — isso é crítico para evitar race conditions onde dois processos simultâneos tentam criar a mesma cobrança.

Estados intermediários: o sistema precisa lidar com o caso em que uma requisição está em processamento quando uma segunda chega com a mesma chave. A Stripe retorna um 409 Conflict nesse caso, sinalizando ao cliente que a operação original ainda está em andamento. Isso é semanticamente correto e evita que o cliente interprete o 409 como uma falha de negócio.

Persistência do resultado: quando o processamento completa — com sucesso ou com erro de negócio (cartão recusado, por exemplo) — o resultado é persistido tanto no PostgreSQL (como parte do registro da cobrança) quanto no Redis com TTL de 24 horas. Erros de negócio também são idempotentes: se a primeira tentativa resultou em card_declined, a segunda tentativa com a mesma chave retorna o mesmo card_declined sem tentar novamente na rede de cartões. Isso é uma decisão de design importante e não óbvia — discutirei no callout.

Retentativas com backoff exponencial: o SDK oficial da Stripe implementa retentativas automáticas com backoff exponencial e jitter para requisições que retornam 5xx ou timeout de rede. A chave de idempotência é gerada uma vez e reutilizada em todas as retentativas da mesma operação. Isso transforma o problema de "como garantir exatamente uma execução" em "como garantir pelo menos uma execução com resultado idempotente" — uma mudança de perspectiva fundamental.

Idempotência resolve o problema de segurança das retentativas, mas não resolve o problema de volume. Um cliente com um bug pode enviar milhares de requisições por segundo — com ou sem chaves de idempotência corretas. O rate limiting é a camada que protege a infraestrutura e garante fairness entre clientes.

A Stripe implementa rate limiting em múltiplas dimensões: por chave de API (conta), por endpoint, e globalmente. A granularidade por endpoint é importante: um endpoint de leitura como GET /charges tem limites mais generosos que um endpoint de escrita como POST /charges, porque o custo de processamento e o risco de efeitos colaterais são diferentes.

O mecanismo técnico mais comum para rate limiting em alta escala é o token bucket ou sliding window counter no Redis. A Stripe não documenta publicamente qual algoritmo usa, mas o comportamento observável — limite de 100 requisições por segundo por chave de API para a maioria dos endpoints em produção — é consistente com um sliding window. O header de resposta Retry-After em respostas 429 é um sinal de design importante: ele diz ao cliente quando pode tentar novamente, transformando um erro em informação acionável.

Um detalhe crítico na interação entre idempotência e rate limiting: uma requisição bloqueada por rate limit não consome a chave de idempotência. Isso é semanticamente correto — o cliente foi impedido de tentar, então a chave permanece disponível para quando ele puder tentar novamente. Se o rate limiter consumisse a chave, o cliente ficaria preso: bloqueado de tentar e com a chave "queimada" para aquela operação.

A Stripe também documenta a prática de idempotência em webhooks: o sistema de entrega de webhooks pode entregar o mesmo evento mais de uma vez (pelo menos uma vez de entrega), e os clientes são orientados a usar o event.id como chave de idempotência no processamento. Isso fecha o loop: a API é idempotente de entrada, e o sistema de notificação é idempotente de saída.

A decisão mais interessante — e mais debatível — no design da Stripe é que erros de negócio também são idempotentes. Se você envia uma requisição com a chave idem_abc123 e o cartão é recusado (card_declined), uma segunda requisição com a mesma chave retorna o mesmo card_declined sem tentar novamente na rede de cartões.

A lógica por trás disso é coerente: a chave de idempotência representa uma intenção específica de cobrança. Se essa intenção resultou em recusa, a recusa é o resultado correto para aquela intenção. Se o cliente quer tentar novamente — talvez o usuário atualizou o cartão, ou quer tentar um cartão diferente — essa é uma nova intenção, que deve ter uma nova chave de idempotência.

Isso tem uma consequência importante para o design de fluxos de pagamento: o cliente precisa entender a diferença entre erros retriáveis (5xx, timeout de rede) e erros não retriáveis (erros de negócio como card_declined, insufficient_funds). Para erros retriáveis, reutilize a chave. Para erros de negócio, gere uma nova chave se quiser tentar novamente com condições diferentes.

Essa distinção é poderosa mas requer educação dos integradores. A Stripe investe pesadamente em documentação e SDKs que encapsulam essa lógica — o SDK Python, por exemplo, automaticamente retenta apenas em erros de rede e 5xx, nunca em 4xx. Isso é design de plataforma: a decisão arquitetural correta implementada de forma que o comportamento padrão seja o comportamento seguro.