Stripe: APIs previsíveis com chaves de idempotência

01 · CONTEXTO

A resposta que não chega

Toda chamada entre dois nós atravessa uma rede, e redes falham de formas exóticas, mesmo as que são estatisticamente confiáveis. Entre um cliente e um servidor há três falhas distintas: a conexão inicial pode nem se estabelecer; a chamada pode cair no meio, enquanto o servidor cumpre a operação, deixando o trabalho em limbo; ou a chamada pode dar certo e a conexão cair antes de o servidor avisar o cliente.

Só a primeira falha é inofensiva: o cliente sabe que nada aconteceu e pode repetir. Nas outras duas o sucesso da operação é ambíguo do ponto de vista do cliente, que não sabe se repetir é seguro. Isso vale para qualquer sistema distribuído, e o artigo lembra que até a API do Stripe com um único outro servidor chamando-a já é um.

1. O cliente envia o pedido de cobrança ao servidor da API.

2. O servidor executa a operação e grava o efeito no banco: a cobrança de fato aconteceu.

3. A conexão cai antes de a resposta chegar. Do ponto de vista do cliente, nada indica se a cobrança foi feita.

4. Se o cliente repetir sem nenhuma proteção, o servidor executa de novo e a cobrança acontece em dobro.

A saída mais simples é projetar o servidor para que repetir seja sempre seguro. Um endpoint com essa propriedade se diz idempotente: pode ser chamado qualquer número de vezes com os efeitos colaterais ocorrendo uma só vez. Diante de qualquer erro, o cliente repete até ter sucesso verificável, e o estado dele converge com o do servidor.

02 · IDEMPOTENTE POR NATUREZA

Quando repetir já é seguro

O artigo usa como exemplo a API de um provedor de DNS hipotético que cria um subdomínio com um PUT. Toda a informação necessária para criar o registro vai na chamada, então o cliente pode invocá-la quantas vezes quiser; se o servidor percebe que é duplicata porque o domínio já existe, ignora o pedido e responde com sucesso. Pela semântica HTTP, PUT e DELETE são idempotentes, e o PUT cria ou substitui o recurso inteiro pelo conteúdo do corpo.

A documentação do Stripe aplica o mesmo raciocínio. Na API v1, GET e DELETE são idempotentes por definição: repeti-los não repete os efeitos da operação original, e mandar chave de idempotência neles não muda nada. Já as requisições POST, que mudam estado, aceitam a chave.

03 · A CHAVE DE IDEMPOTÊNCIA

Exatamente uma vez, mesmo com repetição

E quando a operação precisa ocorrer uma única vez? O exemplo do artigo é um endpoint de cobrança: chamá-lo duas vezes por acidente cobraria o cliente em dobro. A chave de idempotência resolve isso. Ao fazer o pedido, o cliente gera um ID único que identifica só aquela operação e o envia junto do corpo normal; o servidor correlaciona o ID com o estado da requisição do seu lado. Se o cliente notar uma falha, repete com o mesmo ID, e cabe ao servidor decidir o que fazer.

Repare que o artigo não prescreve um único comportamento: o que acontece no caso do meio depende da implementação, e é por isso que a escolha de guardar o estado de cada requisição importa tanto.

1. O cliente gera uma chave única para a operação e a envia junto do corpo normal do pedido.

2. A camada de idempotência consulta o registro. A chave nunca foi vista, então o pedido segue para execução.

3. A operação roda e o servidor guarda no registro o status e o corpo da resposta, depois que a execução do endpoint começa (regra da API v1).

4. A resposta se perde no caminho e o cliente fica sem saber o resultado.

5. O cliente repete com a mesma chave. A camada encontra a resposta salva e a devolve, sem chamar a operação de novo.

6. Se a repetição chegasse com parâmetros diferentes dos originais, a camada recusaria com erro em vez de executar.

Quem gera a chave é o cliente. Como gerá-la fica por conta dele, mas a documentação sugere UUIDs v4 ou outra string aleatória com entropia suficiente para evitar colisões. As chaves têm até 255 caracteres e não devem carregar dados sensíveis, como e-mails ou identificadores pessoais. Uma segunda estratégia é derivar a chave de um objeto ligado ao usuário, como o ID de um carrinho de compras, o que protege de forma direta contra envio duplo.

04 · O QUE O SERVIDOR DECIDE

Executar, devolver ou recusar

Para cada repetição o servidor precisa escolher entre devolver o que já tem, recusar ou executar de verdade. A documentação do Stripe define os casos da API v1, que o quadro abaixo reúne.

O cliente consegue distinguir uma resposta repetida pelo servidor procurando o cabeçalho Idempotent-Replayed com valor verdadeiro.

05 · CICLO DE VIDA DA CHAVE

Janela de repetição e reconciliação

A chave não vive para sempre. O Stripe retém as chaves por pelo menos 24 horas e pode removê-las depois disso, e reutilizar uma chave removida pode executar uma nova requisição. Por isso a orientação é limitar as repetições de uma operação não resolvida às primeiras 24 horas depois da requisição original, sempre com a mesma chave e os mesmos parâmetros.

Se o resultado continua desconhecido depois dessa janela, não se repete nem com a chave antiga nem com uma nova. Em vez disso, busca-se o objeto relevante, inspeciona-se a requisição no painel e usam-se eventos de webhook para reconciliar o resultado.

Outra regra prática: se as repetições atravessam chamadas separadas do SDK ou reinícios de processo, a aplicação deve gerar e persistir a chave da operação e fornecê-la a cada tentativa.

1. Antes da primeira tentativa, a aplicação gera a chave da operação e a persiste.

2. O pedido fica sem resposta. Enquanto a janela permite, a aplicação repete com a mesma chave e os mesmos parâmetros.

3. Se o processo reinicia no meio, a aplicação lê a chave persistida em vez de criar outra.

4. Passada a janela sem resultado conhecido, a aplicação para de repetir, nem com a chave antiga nem com uma nova.

5. A reconciliação busca o objeto e lê os eventos de webhook, casando o que aconteceu com os registros locais.

06 · REPETIR COM EDUCAÇÃO

Recuo exponencial, jitter e as três regras

Repetir também tem custo. Se o servidor está num incidente com indisponibilidade real, as repetições não passam e podem agravar a degradação. Por isso se recomenda um recuo exponencial: o cliente espera pouco após a primeira falha e, conforme a operação continua falhando, espera um tempo proporcional a 2^n, em que n é o número de falhas. Mesmo assim, se muitos clientes falharam quase ao mesmo tempo, os calendários de repetição podem se alinhar e atingir o servidor juntos, o chamado problema do thundering herd. A correção é somar um jitter aleatório à espera de cada cliente.

A biblioteca Ruby do Stripe faz isso sozinha: repete automaticamente em caso de falha, com a mesma chave de idempotência, tempos de espera crescentes e jitter.