Stripe lembra sua solicitação quando a resposta desaparece

O que este vídeo aborda

• Idempotência diz respeito ao efeito pretendido de repetir uma operação. A API v1 do Stripe 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 reinicializações de aplicativos; uma ação genuinamente nova precisa de sua própria chave.
• Após o início da execução do endpoint, a API v1 do Stripe 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 concorrentes não salvam nenhum resultado idempotente para aquela tentativa e podem ser repetidos.
• O Stripe retém as chaves da API v1 por pelo menos 24 horas e pode descartá-las depois. Limite as novas tentativas de rede não resolvidas às primeiras 24 horas, depois pare e reconcilie antes de repetir a operação.
• Um erro 500 armazenado em cache pode continuar sendo reproduzido após a recuperação da conectividade. A operação original pode ter efeitos colaterais; use o objeto relevante, a solicitação do Dashboard e os webhooks para estabelecer seu resultado.
• A API v2 usa semânticas de reprodução diferentes. Uma chave não estabelece entrega universal exatamente uma vez 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 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 com confiança absolutamente nada. Por que uma nova tentativa pode cobrar novamente? Como o Stripe lembra uma tentativa? Quando você deve parar de tentar novamente? E mantenha um detalhe desagradável em mente. Um erro lembrado pode sobreviver ao problema de rede.

0:17 Voltaremos a isso. Este é The Daily Diff, por trás dos bastidores.

O que uma chave de idempotência identifica?

0:21 Idempotência significa que repetir uma operação tem o mesmo efeito pretendido de 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 completa sua solicitação de pagamento, e a resposta se perde ao retornar para casa. O cliente vê um carregamento. Seu banco 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, assim que a execução do endpoint começa, 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 seu 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 erros quinhentos. A documentação faz mais trabalho do que seu auxiliar 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 derrota a proteção.

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

O que acontece quando a solicitação muda?

1:30 Se os parâmetros falharem na validação, ou outra solicitação com essa chave ainda estiver executando, o Stripe não salva nenhum resultado idempotente para aquela tentativa. Essas solicitações podem ser repetidas. Uma solicitação concorrente recebe um conflito. Estas são as regras da versão um. A versão dois se comporta de forma diferente. Um cabeçalho não pode prometer entrega exatamente uma vez em todo o seu sistema. E-mail, 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

Por quanto tempo o resultado lembrado é seguro para nova tentativa?

1:59 descartá-las 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 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 lembrado pode continuar voltando?

2:20 Uma resposta 500 em cache continua sendo reproduzida após a recuperação da conectividade. 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 enviaria um botão de nova tentativa com este contrato?

2:39 Veredito, por trás dos bastidores. 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 esse é o diff de hoje. Sou Niko da Axrisi. Faça merge 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