Pular para o conteúdo
Criar conta
 ou
Entrar
O logotipo da documentação da Stripe
/
Criar conta
Login

Tratamento de erros

Capture e responda a recusas, dados inválidos, problemas de rede e outras ocorrências.

Copiar página

A Stripe oferece vários tipos de erro. Eles podem indicar eventos externos, como pagamentos recusados e interrupções de erro, ou problemas de programação, como chamadas de API inválidas.

Para gerenciar os erros, use algumas ou todas as técnicas da tabela abaixo. Qualquer que seja a técnica usada, você pode complementá-las com nossas respostas recomendadas para cada tipo de erro.

TécnicaObjetivoQuando necessário
Capturar exceçõesRecuperar quando uma chamada de API não consegue continuarSempre
Monitorar webhooksReagir a notificações da StripeAlgumas vezes
Obter informações armazenadas sobre falhasInvestigar problemas passados e apoiar outras técnicasAlgumas vezes

Capturar exceções

Se um problema imediato evita a continuidade de uma chamada de API, a biblioteca Ruby da Stripe gera uma exceção. Capturar e gerenciar exceções é uma prática recomendada.

Para capturar uma exceção, use a palavra-chave rescue do Ruby. Capture Stripe::StripeError ou suas subclasses para gerenciar apenas exceções específicas da Stripe. Cada subclasse representa um tipo diferente de exceção. Quando captura uma exceção, você pode usar suas classes para escolher uma resposta.

require 'stripe'

Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    puts "A payment error occurred: #{e.error.message}"
  rescue Stripe::InvalidRequestError => e
    puts "An invalid request occurred."
  rescue Stripe::StripeError => e
    puts "Another problem occurred, maybe unrelated to Stripe."
  else
    puts "No error."
  end
end

Depois de configurar o gerenciamento de exceções, teste-o com diversos dados, incluindo cartões de teste, para simular diversos resultados de pagamentos.

example_function(
  # The required parameter currency is missing,
  amount: 2000,
  confirm: true,
  payment_method: 
'pm_card_visa'
,
)
console
An invalid request occurred.

Monitorar webhooks

A Stripe notifica diversos tipos de problema usando webhooks, inclusive problemas que não ocorrem imediatamente após uma chamada de API. Por exemplo:

  • Você perde uma contestação.
  • Um pagamento recorrente falha após vários pagamentos mensais bem-sucedidos.
  • O front-end confirma um pagamento, mas fica offline antes de saber que o pagamento falhou (o back-end recebe a notificação do webhook, embora não tenha feito a chamada de API).

Você não precisa gerenciar todos os tipos de evento de webhook. Na verdade, algumas integrações não gerenciam nenhum deles.

No gerenciador de webhooks, comece com as etapas básicas do criador de webhooks: obtenha um objeto de evento e use o tipo do evento para descobrir o que ocorreu. Se o tipo de evento indicar um erro, siga estas etapas adicionais:

  1. Acesse event.data.object para recuperar o objeto afetado.
  2. Use informações armazenadas no objeto afetado para obter contexto, incluindo um objeto de erro.
  3. Use seu tipo para escolher uma resposta.
require 'stripe'
require 'sinatra'
post '/webhook' do
  payload = request.body.read
  data = JSON.parse(payload, symbolize_names: true)

  # Get the event object
  event = Stripe::Event.construct_from(data)

  # Use the event type to find out what happened
  case event.type
  when 'payment_intent.payment_failed'

    # Get the object affected
    payment_intent = event.data.object

    # Use stored information to get an error object
    e = payment_intent.last_payment_error

    # Use its type to choose a response
    case e.type
    when 'card_error'
      puts "A payment error occurred: #{e.message}"
    when 'invalid_request'
      puts "An invalid request occurred."
    else
      puts "Another problem occurred, maybe unrelated to Stripe."
    end
  end

  content_type 'application/json'
  {
    status: 'success'
  }.to_json
end

Para testar como sua integração responde a eventos de webhook, você pode acionar eventos de webhook localmente. Depois de concluir as etapas de configuração nesse link, acione um pagamento com falha para ver a mensagem de erro resultante.

Command Line
stripe trigger payment_intent.payment_failed
Output
A payment error occurred: Your card was declined.

Obter informações armazenadas sobre falhas

Muitos objetos armazenam informações sobre falhas. Isso significa que, se algo já deu errado, você pode recuperar o objeto e examiná-lo para saber mais. Em muitos casos, as informações armazenadas estão na forma de um objeto de erro e você pode usar seu tipo para escolher uma resposta.

Por exemplo:

  1. Recupere uma intenção de pagamento específica.
  2. Para saber se houve um erro de pagamento na intenção, verifique se last_payment_error está vazio.
  3. Se ocorreu, registre o erro, incluindo seu tipo e o objeto afetado.
require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


payment_intent = Stripe::PaymentIntent.retrieve(
'{{PAYMENT_INTENT_ID}}'
)
e = payment_intent.last_payment_error
if !e.nil?
  puts "PaymentIntent #{payment_intent.id} experienced a #{e.type}."
end

Veja a seguir os objetos comuns que armazenam informações sobre falhas.

ObjetoAtributoValores
Payment Intentlast_payment_errorUm objeto de erro
Setup Intentlast_setup_errorUm objeto de erro
Invoicelast_finalization_errorUm objeto de erro
Setup Attemptsetup_errorUm objeto de erro
Payoutfailure_codeUm código de falha de repasse
Refundfailure_reasonUm código de falha de reembolso

Muitas vezes, para testar uma programação que usa dados armazenados sobre falhas, você precisa simular falhas em transações. Normalmente, isso pode ser feito usando cartões de teste ou números bancários de teste. Por exemplo:

Tipos de erro e respostas

Na biblioteca Ruby da Stripe, os objetos de erro pertencem a stripe.error.StripeError e suas subclasses. Use a documentação de cada classe para saber como responder.

Nome

Classe

Descrição
Erro de pagamento

Stripe::CardError

Ocorreu um erro durante um pagamento que envolve uma destas situações:
Erro de solicitação inválida

Stripe::InvalidRequestError

Você fez uma chamada de API com parâmetros errados, no estado errado ou de forma inválida.

Erro de conexão

Stripe::APIConnectionError

Ocorreu um problema de rede entre o seu servidor e a Stripe.
Erro de API

Stripe::APIError

Ocorreu um erro no lado da Stripe (raramente acontece).
Erro de autenticação

Stripe::AuthenticationError

A Stripe não consegue autenticar você com os dados informados.
Erro de idempotência

Stripe::IdempotencyError

You used an idempotency key for something unexpected, like replaying a request but passing different parameters.
Erro de permissão

Stripe::PermissionError

A chave de API usada para esta solicitação não tem as permissões necessárias.
Erro de limitação de fluxo

Stripe::RateLimitError

Você fez um número excessivo de chamadas de API em um período curto demais.
Erro de verificação de assinatura

Stripe::SignatureVerificationError

You’re using webhook signature verification and couldn’t verify that a webhook event is authentic.

Erros de pagamento

Os erros de pagamento (chamados às vezes de “erros de cartão” por motivos históricos) abrangem uma grande variedade de problemas comuns. Eles pertencem a três categorias:

To distinguish these categories or get more information about how to respond, consult the error code, decline code, and charge outcome.

(To find the charge outcome from an error object, first get the Payment Intent that’s involved and the latest Charge it created. See the example below for a demonstration.)

require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    charge = Stripe::Charge.retrieve(e.error.payment_intent.latest_charge)
    if charge.outcome.type == 'blocked'
      puts 'Payment blocked for suspected fraud.'
    elsif e.code == 'card_declined'
      puts 'Payment declined by the issuer.'
    elsif e.code == 'expired_card'
      puts 'Card expired.'
    else
      puts 'Other card error.'
    end
  end
end

Users on API version 2022-08-01 or older:

(To find the charge outcome from an error object, first get the Payment Intent that’s involved and the latest Charge it created. See the example below for a demonstration.)

require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    if e.error.payment_intent.charges.data[0].outcome.type == 'blocked'
      puts 'Payment blocked for suspected fraud.'
    elsif e.code == 'card_declined'
      puts 'Payment declined by the issuer.'
    elsif e.code == 'expired_card'
      puts 'Card expired.'
    else
      puts 'Other card error.'
    end
  end
end

Você pode acionar alguns tipos comuns de erro de pagamento com cartões de teste. Consulte estas listas para ver as opções:

O código de teste abaixo demonstra algumas possibilidades.

example_function(
  currency: 'usd',
  amount: 2000,
  confirm: true,
  payment_method: 
'pm_card_radarBlock'
,
)
console
Payment blocked for suspected fraud.

Pagamento bloqueado por suspeita de fraude

Tipo

Stripe::CardError

Códigos
charge = Stripe::Charge.retrieve(e.error.payment_intent.latest_charge)
charge.outcome.type == 'blocked'
Códigos

e.error.payment_intent.charges.data[0].outcome.type == 'blocked'

ProblemaO sistema de prevenção de fraudes da Stripe, o Radar, bloqueou o pagamento

Soluções

Este erro pode ocorrer quando a integração está funcionando corretamente. Capture o erro e solicite outra forma de pagamento do cliente.

Para bloquear menos pagamentos legítimos, experimente:

Os clientes do Radar for Fraud Teams têm estas opções adicionais:

  • Para isentar um pagamento específico, adicione-o à lista de permissões. Radar for Fraud Teams
  • To change your risk tolerance, adjust your risk settings. Radar for Fraud Teams
  • To change the criteria for blocking a payment, use custom rules. Radar for Fraud Teams

You can test your integration’s settings with test cards that simulate fraud. If you have custom Radar rules, follow the testing advice in the Radar documentation.

Pagamento recusado pelo emissor

Tipo

Stripe::CardError

Códigos

e.error.code == "card_declined"

ProblemaO emissor do cartão recusou o pagamento.

Soluções

This error can occur when your integration is working correctly. It reflects an action by the issuer, and that action might be legitimate. Use the decline code to determine what next steps are appropriate. See the documentation on decline codes for appropriate responses to each code.

Você também pode:

Test how your integration handles declines with test cards that simulate successful and declined payments.

Outros erros de pagamento

Tipo

Stripe::CardError

ProblemaOcorreu outro erro de pagamento.
SoluçõesThis error can occur when your integration is working correctly. Use the error code to determine what next steps are appropriate. See the documentation on error codes for appropriate responses to each code.

Erros de solicitação inválida

Tipo

Stripe::InvalidRequestError

ProblemaVocê fez uma chamada de API com parâmetros errados, no estado errado ou de forma inválida.
SoluçõesNa maioria dos casos, o problema é da própria solicitação. Os parâmetros são inválidos ou não podem ser executados no estado atual da integração.
  • Consult the error code documentation for details on the problem.
  • Para sua conveniência, acesse o link em para ver a documentação sobre o código de erro.
  • Se o erro envolver um parâmetro específico, use para determinar qual deles.

Erros de conexão

Tipo

Stripe::APIConnectionError

ProblemaOcorreu um problema de rede entre o seu servidor e a Stripe.

Soluções

Treat the result of the API call as indeterminate. That is, don’t assume that it succeeded or that it failed.

Para descobrir se deu certo:

  • Recupere o objeto relevante da Stripe e verifique seu status.
  • Ouça a notificação de webhook sobre o sucesso ou falha da operação.

To help recover from connection errors, you can:

  • When creating or updating an object, use an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of creating a second object or performing the update twice. Repeat the request with the same idempotency key until you receive a clear success or failure. For advanced advice on this strategy, see Low-level error handling.
  • Ative as tentativas automáticas. Dessa forma, a Stripe gera chaves de idempotência para você e repete as solicitações quando for seguro fazer isso.

Esse erro pode mascarar outros. Pode ser que outro erro se torne aparente quando o erro de conexão for resolvido. Verifique a ocorrência de erros em todas essas soluções da mesma forma que faria na solicitação original.

Erros de API

Tipo

Stripe::APIError

ProblemaOcorreu um erro no lado da Stripe (raramente acontece).

Soluções

Trate o resultado da chamada de API como indeterminado. Ou seja, não suponha que foi bem ou malsucedido.

Use webhooks para obter informações sobre o resultado. Sempre que possível, a Stripe aciona webhooks para todos os objetos que criamos durante a solução de um problema.

To set your integration up for maximum robustness in unusual situations, see this advanced discussion of server errors.

Erros de autenticação

Tipo

Stripe::AuthenticationError

ProblemaA Stripe não consegue autenticar você com os dados informados.
Soluções

Erros de idempotência

Tipo

Stripe::IdempotencyError

ProblemaYou used an idempotency key for something unexpected, like replaying a request but passing different parameters.
Soluções
  • Depois de usar uma chave de idempotência, reutilize-a apenas em chamadas de API idênticas.
  • Use chaves de idempotência respeitando o limite de 255 caracteres.

Erros de permissão

Tipo

Stripe::PermissionError

ProblemaThe API key used for this request doesn’t have the necessary permissions.
Soluções
  • Make sure you aren’t using a restricted API key for a service it doesn’t have access to.
  • Don’t perform actions in the Dashboard while logged in as a user role that lacks permission.

Erros de limitação de fluxo

Tipo

Stripe::RateLimitError

ProblemaVocê fez um número excessivo de chamadas de API em um período curto.
Soluções
  • Se uma única chamada de API acionar esse erro, aguarde e tente novamente.
  • To handle rate-limiting automatically, retry the API call after a delay, and increase the delay exponentially if the error continues. See the documentation on rate limits for further advice.
  • Se você espera um grande aumento de tráfego e quer solicitar uma limitação de fluxo maior, fale antecipadamente com o suporte.

Erros de verificação de assinatura

Tipo

Stripe::SignatureVerificationError

ProblemaYou’re using webhook signature verification and couldn’t verify that a webhook event is authentic.

Soluções

Este erro pode ocorrer quando a integração está funcionando corretamente. Se você usa verificação de assinatura de webhooks e um terceiro tenta enviar um webhook falso ou mal-intencionado, a verificação falha e gera este erro. Capture o erro e responda com um código de status 400 Bad Request.

If you receive this error when you shouldn’t—for instance, with webhooks that you know originate with Stripe—then see the documentation on checking webhook signatures for further advice. In particular, make sure you’re using the correct endpoint secret. This is different from your API key.

Esta página foi útil?
SimNão
Precisa de ajuda? Fale com o suporte.
Participe do nosso programa de acesso antecipado.
Confira nosso changelog.
Dúvidas? Fale com a equipe de vendas.
LLM? Read llms.txt.
Powered by Markdoc