Stripe lembra-se do seu pedido quando a resposta desaparece

O que este vídeo aborda

• A idempotência refere-se ao efeito pretendido de repetir uma operação. A API Stripe v1 adiciona um contrato de reprodução de resposta salva documentado.
• Uma nova tentativa da mesma ação lógica usa a mesma chave e parâmetros. Persista a chave de operação em chamadas de SDK separadas ou reinícios de aplicativos; uma ação genuinamente nova precisa da sua própria chave.
• Após o início da execução do endpoint, a API Stripe v1 salva o status e o corpo da primeira solicitação, incluindo erros 500, e retorna essa resposta salva em novas tentativas.
• Parâmetros alterados com a mesma chave produzem uma incompatibilidade. Falhas de validação e conflitos de execução concorrente não salvam nenhum resultado idempotente para essa tentativa e podem ser repetidos.
• Stripe retém chaves da API v1 por pelo menos 24 horas e pode descartá-las posteriormente. Limite as novas tentativas de rede não resolvidas às primeiras 24 horas, depois pare e reconcilie antes de repetir a operação.
• Um 500 em cache pode continuar a ser reproduzido depois que a conectividade for recuperada. A operação original pode ter efeitos colaterais; use o objeto relevante, a solicitação do Dashboard e os webhooks para estabelecer o seu resultado.
• A API v2 usa semânticas de reprodução diferentes. Uma chave não estabelece uma entrega "exatamente uma vez" universal para e-mail, inventário e cada operação de banco de dados local.

Transcrição traduzida

Traduzido da narração original em inglês. Áudio e legendas disponíveis são controlados pelo YouTube.

Um tempo limite cancelou o seu pagamento?

0:00 Você acha que um tempo limite significa que seu pagamento falhou. O servidor pode terminar enquanto a resposta desaparece, deixando seu checkout exibindo absolutamente nada com confiança. Por que uma nova tentativa pode cobrar novamente? Como o Stripe se lembra de uma tentativa? Quando você deve parar de tentar novamente? E mantenha um detalhe desagradável em mente. Um erro memorizado pode sobreviver ao problema de rede.

0:17 Voltaremos a isso. Este é The Daily Diff, por baixo do capô.

O que uma chave de idempotência identifica?

0:21 Idempotência significa que repetir uma operação tem o mesmo efeito pretendido que fazê-la uma vez. Uma chave de idempotência rotula uma ação lógica. A versão um da API do Stripe reconhece esse rótulo em novas tentativas e reproduz uma resposta salva. Imagine comprar um café. Stripe conclui sua solicitação de pagamento, e a resposta se perde ao retornar para casa. O cliente vê um spinner. O banco deles pode ter uma interpretação mais emocionante. Uma solicitação de criação desprotegida pode repetir o efeito colateral.

Como a mesma chave torna uma nova tentativa segura?

0:45 Anexe uma chave exclusiva antes da primeira tentativa e mantenha-a para novas tentativas. Se seu aplicativo reiniciar, preserve essa chave com a operação em seus registros. Para a API versão um do Stripe, uma vez iniciada a execução do endpoint, o status e o corpo da primeira solicitação são salvos. Envie a mesma chave e parâmetros novamente, e o Stripe retorna a resposta salva. O café permanece no lugar enquanto o recibo viaja novamente.

O que exatamente o Stripe salva?

1:07 Aqui está a redação real do Stripe. Novas tentativas com a mesma chave retornam a resposta salva, incluindo quinhentos erros. A documentação faz mais trabalho do que seu ajudante de nova tentativa otimista. O cliente toca novamente. Seu aplicativo decide se isso retoma a compra pendente ou inicia outra. Um café genuinamente novo recebe uma nova chave. Uma chave nova para cada nova tentativa de rede anula a proteção.

1:27 Parâmetros diferentes com a mesma chave acionam uma incompatibilidade.

O que acontece quando o pedido muda?

1:30 Se os parâmetros falharem na validação, ou outra solicitação com essa chave ainda estiver em execução, o Stripe não salva nenhum resultado idempotente para essa tentativa. Essas solicitações podem ser repetidas. Uma solicitação concorrente gera um conflito. Estas são as regras da versão um. A versão dois comporta-se de forma diferente. Um cabeçalho não pode prometer entrega "exatamente uma vez" em todo o seu sistema. Email, inventário e seu banco de dados precisam de tratamento de falhas.

1:52 A chave protege a operação dentro de seu escopo documentado. O Stripe retém as chaves da versão um por pelo menos vinte e quatro horas e pode descartá-las

Por quanto tempo o resultado memorizado é seguro para tentar novamente?

1:59 depois. Uma chave descartada pode executar uma nova solicitação. Mantenha as novas tentativas não resolvidas dentro do primeiro dia. Além disso, pare e reconcilie o resultado original. Use backoff exponencial e jitter para dar espaço de manobra ao servidor. Caso contrário, as novas tentativas formam uma fila fora de uma cafeteria em chamas. As bibliotecas do Stripe lidam com novas tentativas, mas verifique os padrões da sua biblioteca. Esse erro persistente é o problema.

Por que um erro memorizado pode continuar a voltar?

2:20 Uma resposta quinhentos em cache continua a ser reproduzida depois que a conectividade é recuperada. A operação original pode ter produzido efeitos colaterais. Resolva seu resultado usando objetos, o Dashboard e webhooks. Uma nova chave pode repetir a ação. Se você preferir ler isso a me ouvir dizer, o diff chega à sua caixa de entrada todas as manhãs, gratuitamente em the daily diff dot dev, link abaixo.

Eu lançaria um botão de nova tentativa com este contrato?

2:39 Veredito, por baixo do capô. Envie. Eu enviaria chaves estáveis com novas tentativas limitadas e reconciliação, para que os clientes recebam café sem financiar sua educação em sistemas distribuídos. E essa é a diferença de hoje. Sou Niko da Axrisi. Faça a fusão com responsabilidade.

Fontes

1. Idempotent requestsStripe Docs
2. Designing robust and predictable APIs with idempotencyStripe Engineering — Brandur Leach
3. Advanced error handlingStripe Docs
4. HTTP Semantics — RFC 9110 §9.2.2 Idempotent MethodsIETF / RFC Editor