Tratamento de erros avançado

Esta página aborda dois tópicos avançados de tratamento de erros:

• Respostas HTTP que representam erros
• Idempotência e novas tentativas

Essas informações podem não se aplicar a você. Os SDKs oficiais da Stripe podem gerenciar a maioria dos detalhes envolvendo HTTP e novas tentativas. Se você usa uma biblioteca de cliente, comece aqui:

• Tratamento de erros
• Códigos de erro

Erros em HTTP

Mesmo quando uma chamada de API falha, nossas bibliotecas de cliente disponibilizam informações sobre erros gerando uma exceção ou retornando um valor de erro. No entanto, se você não usa uma biblioteca cliente, ou se uma situação incomum surgir, talvez você precise de detalhes de nível inferior sobre as respostas HTTP e quando as emitirmos.

Do ponto de vista de HTTP, os erros se enquadram em três categorias principais:

• Erro de conteúdo: Conteúdo inválido na solicitação da API.
• Erro de rede: Problemas intermitentes de comunicação entre cliente e servidor.
• Erro do servidor: Um problema nos servidores da Stripe.

Cada tipo de erro requer uma abordagem e semântica de idempotência diferentes. Lista completa de códigos de resposta e seu significado são fornecidos no final desta página.

Erros de conteúdo

Os erros de conteúdo resultam do conteúdo inválido de uma solicitação de API. Eles retornam uma resposta HTTP com um código de resposta 4xx. Por exemplo, os servidores API podem retornar um 401 se você forneceu uma chave API inválida ou um 400 se um parâmetro obrigatório estiver faltando. As integrações devem corrigir a solicitação original e tentar novamente. Dependendo do tipo de erro do usuário (por exemplo, um cartão sendo recusado), pode ser possível resolver o problema automaticamente. Nesses casos, inclua um campo code para ajudar a integração a reagir adequadamente. Consulte códigos de erro para obter mais detalhes.

Em uma operação POST que usa uma chave de idempotência, desde que a execução tenha sido iniciada por um método de API, os servidores de API da Stripe armazenam os resultados da solicitação em cache, qualquer que seja o seu conteúdo. Uma solicitação que retorna um código 400 envia novamente um código 400 para uma nova solicitação que usa a mesma chave de idempotência. Para obter um resultado bem-sucedido, gere uma nova chave de idempotência quando modificar a solicitação original. Essa operação apresenta algumas restrições. Por exemplo, uma solicitação com limitação de fluxo com código 429 pode gerar um resultado diferente com a mesma chave de idempotência, pois os limitadores de fluxo são executados antes da camada de idempotência da API. O mesmo ocorre para um código 401 que omitiu uma chave de API ou para a maioria dos códigos 400 que enviaram parâmetros inválidos. Mesmo assim, a estratégia mais segura para erros 4xx é gerar sempre uma nova chave de idempotência.

Erros de rede

Os erros de rede são o resultado de problemas de conectividade entre cliente e servidor. Eles retornam erros de baixo nível, como exceções de soquete ou tempo esgotado. Por exemplo, um cliente pode atingir o tempo limite ao tentar ler a partir dos servidores da Stripe ou uma resposta da API pode nunca ser recebida porque uma conexão é encerrada prematuramente. Embora um erro de rede pareça que será bem-sucedido depois que você corrigir os problemas de conectividade, às vezes há outro tipo de erro oculto no problema intermitente.

É neste tipo de erros que o valor das chaves de idempotência e das novas tentativas de solicitação é mais óbvio. Quando ocorrem problemas intermitentes, os clientes costumam ficar em um estado em que não sabem se o servidor recebeu a solicitação. Para obter uma resposta definitiva, eles devem tentar novamente essas solicitações com as mesmas chaves de idempotência e os mesmos parâmetros, até receberem um resultado do servidor. O envio da mesma idempotência com parâmetros diferentes gera um erro que indica que a nova solicitação não corresponde à original.

A maioria das bibliotecas de cliente pode gerar automaticamente chaves de idempotência e novas tentativas de solicitação, mas precisa ser configurada para isso. Elas executam a primeira nova tentativa logo depois da primeira falha. As repetições subsequentes são realizadas em intervalos que aumentam exponencialmente, pois se supõe que um falha única seja geralmente uma ocorrência aleatória, mas falhas repetidas devem resultar de um problema crônico.

Stripe.max_network_retries = 2

Erros de servidor

Os erros de servidor resultam de um problema com os servidores da Stripe. Eles retornam uma resposta HTTP com um código de erro 5xx. Esses erros são os mais difíceis de tratar e trabalhamos para que eles ocorram o menos possível, mas uma boa integração os administra quando ocorrem.

Assim como nos erros de usuário, a camada de idempotência armazena em cache o resultado de mutações de POST que resultam em erros de servidor (especificamente, erros 500, que são erros internos de servidor). Portanto, novas tentativas com a mesma chave de idempotência costumam produzir o mesmo resultado. O cliente pode tentar novamente a solicitação com uma nova chave de idempotência, mas não recomendamos essa abordagem, porque a chave original pode ter gerado efeitos colaterais.

Você deve tratar o resultado de uma solicitação 500 como indeterminado. O momento mais provável para observar isso é durante um incidente de produção e, geralmente, durante a remediação desse incidente. Os engenheiros da Stripe examinam solicitações fracassadas e tentam reconciliar adequadamente os resultados de quaisquer mutações que resultem em erros 500. Embora a resposta em cache de idempotência a essas solicitações não mude, tentaremos disparar webhooks para todos os novos objetos criados como parte da reconciliação da Stripe. A natureza exata de qualquer alteração retroativa no sistema depende muito do tipo de solicitação. Por exemplo, se a criação de uma cobrança retornar um erro 500, mas detectarmos que os dados foram enviados para uma rede de pagamento, tentaremos implementá-la. Caso contrário, tentaremos revertê-la. Se isso não resolver o problema, você ainda poderá ver solicitações com um erro 500 que produzem efeitos colaterais visíveis pelo usuário.

Para permitir que sua integração gerencie a maior variedade de 500s, configure gerenciadores de webhooks para receber objetos de evento que você nunca recebe em respostas de API normais. Uma técnica de referência cruzada desses novos objetos com os dados do estado local de uma integração é enviar um identificador local com os metadados ao criar novos recursos com a API. Esse identificador aparece no campo de metadados de um objeto saindo de um webhook, mesmo que o webhook seja gerado posteriormente durante a reconciliação.

Idempotência

Idempotência é um princípio de design de API da web definido como a capacidade de aplicar a mesma operação várias vezes sem alterar o resultado além da primeira tentativa. Ele torna seguro tentar novamente as solicitações da API em algumas situações, especialmente quando a primeira solicitação não recebe resposta devido a um erro de rede. Como uma certa quantidade de falhas intermitentes é esperada, os clientes precisam de uma maneira de reconciliar solicitações com falha com um servidor, e a idempotência fornece um mecanismo para isso.

A maioria das bibliotecas de cliente pode gerar automaticamente chaves de idempotência e novas tentativas de solicitação, mas você precisa configurá-las. Para um controle mais refinado sobre novas tentativas, gere chaves de idempotência e crie sua própria lógica para novas tentativas.

OBTER e EXCLUIR solicitações

A API da Stripe garante a idempotência das solicitações GET e DELETE, por isso é sempre seguro tentar novamente.

Solicitações de POSTAGEM

A inclusão de uma chave de idempotência torna as solicitações POST idempotentes, o que solicita que a API faça a manutenção dos registros necessários para evitar operações duplicadas. Os clientes podem tentar novamente com segurança solicitações que incluam uma chave de idempotência, desde que a segunda solicitação ocorra dentro de 24 horas a partir de quando você recebe a chave pela primeira vez (as chaves expiram fora do sistema após 24 horas). Por exemplo, se uma solicitação para criar um objeto não responder devido a um erro de conexão de rede, um cliente poderá tentar novamente a solicitação com a mesma chave de idempotência para garantir que não mais de um objeto seja criado.

Enviar chaves de idempotência

As chaves de idempotência são enviadas no cabeçalho Idempotency-Key. Use-os em todas as solicitações POST para a API da Stripe. A maioria das bibliotecas de clientes oficiais pode enviá-las automaticamente, desde que estejam configuradas para enviar novas tentativas.

Se você decidir enviar chaves de idempotência manualmente, certifique-se de que os tokens em uso sejam suficientemente únicos para identificar sem ambiguidades uma operação isolada em sua conta nas últimas 24 horas, no mínimo. Existem duas estratégias comuns para gerar chaves de idempotência:

• Use um algoritmo que gera um token com aleatoriedade suficiente, como UUID v4.
• Derive a chave de um objeto fixado a um usuário, como o ID de um carrinho de compra. Isso proporciona uma maneira relativamente objetiva de proteger contra envios duplos.

Para identificar uma resposta previamente executada que está sendo repetida do servidor, procure o cabeçalho Idempotent-Replayed: true.

O cabeçalho Stripe-Should-Retry

Uma biblioteca de cliente nem sempre consegue determinar com certeza se deve tentar novamente com base em um código de status ou conteúdo no corpo da resposta. A API responde com o cabeçalho Stripe-Should-Retry quando tem informações adicionais de que a solicitação pode ser tentada novamente.

• Stripe-Should-Retry definido como true indica que um cliente deve tentar novamente a solicitação. Os clientes devem continuar a aguardar a mesma quantidade de tempo (provavelmente determinada de acordo com intervalos que aumentam exponencialmente) antes de fazer a próxima solicitação para não sobrecarregar a API.
• Stripe-Should-Retry definido como false significa que um cliente não deve tentar novamente a solicitação, pois não terá efeitos adicionais.
• Stripe-Should-Retry não definido na resposta indica que a API não consegue determinar se pode tentar novamente a solicitação. Os clientes devem recorrer a outras propriedades da resposta (como o código de status) para decidir.

Os mecanismos de novas tentativas incorporados às bibliotecas cliente da Stripe respeitam automaticamente o Stripe-Should-Retry. Se estiver usando um desses modelos, não precisa de tratamento manual.

Referência de código de status HTTP