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 impedir que uma chamada API continue, a biblioteca Node.js da Stripe pode gerar uma exceção. É uma prática recomendada capturar e gerenciar exceções. Para habilitar a geração da exceção e capturá-la, faça o seguinte:

  • Se a chamada de API é feita em uma função, acrescente a palavra-chave async ao início da definição da função.
  • Acrescente a palavra-chave await ao início da própria chamada de API.
  • Encapsule a chamada de API em um bloco try/catch.

Quando captura uma exceção, você pode usar o atributo de tipo para escolher uma resposta.

const stripe = require('stripe')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

async function exampleFunction(args) {
  try {
    const paymentIntent = await stripe.paymentIntents.create(args);
    console.log('No error.');
  } catch (e) {
    switch (e.type) {
      case 'StripeCardError':
        console.log(`A payment error occurred: ${e.message}`);
        break;
      case 'StripeInvalidRequestError':
        console.log('An invalid request occurred.');
        break;
      default:
        console.log('Another problem occurred, maybe unrelated to Stripe.');
        break;
    }
  }
}

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

exampleFunction({
  // 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.
const stripe = require('stripe')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);
const express = require('express');
const app = express();

app.post('/webhook', express.json({type: 'application/json'}), (request, response) => {

  // Get an event object
  const event = request.body;

  // Use its type to find out what happened
  if (event.type == 'payment_intent.payment_failed') {

    // Get the object affected
    const paymentIntent = event.data.object;

    // Use stored information to get an error object
    const error = paymentIntent.last_payment_error;

    // Use its type to choose a response
    switch (error.type) {
      case 'card_error':
        console.log(`A payment error occurred: ${error.message}`);
        break;
      case 'invalid_request_error':
        console.log('An invalid request occurred.');
        if (error.param) {
          console.log(`The parameter ${error.param} is invalid or missing.`);
        }
        break;
      default:
        console.log('Another problem occurred, maybe unrelated to Stripe.');
        break;
    }
  }
  response.send();
});

app.listen(4242, () => console.log('Running on port 4242'));

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.
const stripe = require('stripe')(
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

const payment_intent = await stripe.paymentIntents.retrieve(
'{{PAYMENT_INTENT_ID}}'
)

const e = payment_intent.last_payment_error

if (e !== null) {
  console.log(`PaymentIntent ${payment_intent.id} experienced a ${e.type} error.`)
}

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 Node.js da Stripe, cada objeto de erro tem um atributo type. Use a documentação de cada tipo para obter orientações sobre como responder.

Nome

Tipo

Descrição
Erro de pagamento

StripeCardError

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

StripeInvalidRequestError

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

Erro de conexão

StripeConnectionError

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

StripeAPIError

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

StripeAuthenticationError

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

StripeIdempotencyError

Você usou uma chave de idempotência para algo inesperado, como repetir uma solicitação passando parâmetros diferentes.
Erro de permissão

StripePermissionError

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

StripeRateLimitError

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

StripeSignatureVerificationError

Você está usando verificação de assinatura de webhooks e não conseguiu verificar a autenticidade de um evento de webhook.

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:

Para distinguir essas categorias ou obter mais informações sobre como responder, consulte o código de erro, o código de recusa e o resultado da cobrança.

(Para encontrar o resultado da cobrança de um objeto de erro, obtenha primeiro o Payment Intent envolvido e a última cobrança criada. Veja uma demonstração no exemplo abaixo.)

const stripe = require('stripe')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

async function exampleFunction(args) {
    try {
      const paymentIntent = await stripe.paymentIntents.create(args);
    } catch (e) {
      console.log(e)
      const charge = await stripe.charges.retrieve(e.payment_intent.latest_charge)
      if (e.type === 'StripeCardError') {
        if (charge.outcome.type === 'blocked') {
          console.log('Payment blocked for suspected fraud.')
        } else if (e.code === 'card_declined') {
          console.log('Payment declined by the issuer.')
        } else if (e.code === 'expired_card') {
          console.log('Card expired.')
        } else {
          console.log('Other card error.')
        }
      }
    }
  }

Usuários na versão 2022-08-01 da API ou mais antiga:

(Para encontrar o resultado da cobrança de um objeto de erro, obtenha primeiro o Payment Intent envolvido e a última cobrança criada. Veja uma demonstração no exemplo abaixo.)

const stripe = require('stripe')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

async function exampleFunction(args) {
    try {
      const paymentIntent = await stripe.paymentIntents.create(args);
    } catch (e) {
      console.log(e)
      if (e.type === 'StripeCardError') {
        if (e.payment_intent.charges.data[0].outcome.type === 'blocked') {
          console.log('Payment blocked for suspected fraud.')
        } else if (e.code === 'card_declined') {
          console.log('Payment declined by the issuer.')
        } else if (e.code === 'expired_card') {
          console.log('Card expired.')
        } else {
          console.log('Other card error.')
        }
      }
    }
  }

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.

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

Pagamento bloqueado por suspeita de fraude

Tipo

StripeCardError

Códigos
const charge = await stripe.charges.retrieve(e.payment_intent.latest_charge)
charge.outcome.type === 'blocked'
Códigos

e.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
  • Para alterar a tolerância ao risco, ajuste as configurações de risco. Radar for Fraud Teams
  • Para alterar os critérios de bloqueio de um pagamento, use regras personalizadas. Radar for Fraud Teams

Você pode testar as configurações da integração com cartões de teste que simulam fraudes. Se você tiver regras de Radar personalizadas, siga as orientações de teste da documentação de Radar.

Pagamento recusado pelo emissor

Tipo

StripeCardError

Códigos

e.code === 'card_declined'

ProblemaO emissor do cartão recusou o pagamento.

Soluções

Este erro pode ocorrer quando a integração está funcionando corretamente. Ela reflete uma ação do emissor, que pode ser legítima. Use o código de recusa para determinar as próximas etapas adequadas. Consulte a documentação sobre códigos de recusa para obter as respostas adequadas a cada código.

Você também pode:

Teste como sua integração gerencia recusas com cartões de teste que simulam pagamentos bem-sucedidos e recusados.

Outros erros de pagamento

Tipo

StripeCardError

ProblemaOcorreu outro erro de pagamento.
SoluçõesEste erro pode ocorrer quando a integração está funcionando corretamente. Use o código de erro para determinar quais são as próximas etapas apropriadas. Consulte a documentação sobre códigos de erro para obter as respostas adequadas para cada código.

Erros de solicitação inválida

Tipo

StripeInvalidRequestError

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.
  • Consulte a documentação do código de erro para obter detalhes sobre o problema.
  • Para sua conveniência, acesse o link em e.doc_url para ver a documentação sobre o código de erro.
  • Se o erro envolver um parâmetro específico, use e.param para determinar qual deles.

Erros de conexão

Tipo

StripeAPIConnectionError

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

Soluções

Trate o resultado da chamada da API como indeterminado. Ou seja, não assuma que deu certo ou que falhou.

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.

Para recuperar-se de erros de conexão, você pode tentar:

  • Ao criar ou atualizar um objeto, use uma chave de idempotência. Em seguida, se ocorrer um erro de conexão, você poderá repetir a solicitação com segurança sem risco de criar um segundo objeto ou executar a atualização duas vezes. Repita a solicitação com a mesma chave de idempotência até receber claramente um êxito ou falha. Para obter orientações avançadas sobre essa estratégia, consulte Tratamento de erros em nível inferior.
  • 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

StripeAPIError

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.

Para configurar a integração com o máximo de robustez em situações incomuns, consulte discussão avançada sobre erros de servido.

Erros de autenticação

Tipo

StripeAutheticationError

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

Erros de idempotência

Tipo

StripeIdempotencyError

ProblemaVocê usou uma chave de idempotência para algo inesperado, como repetir uma solicitação passando parâmetros diferentes.
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

StripePermissionError

ProblemaA chave de API usada para esta solicitação não tem as permissões necessárias.
Soluções
  • Verifique se você não está usando uma chave de API restrita para um serviço ao qual ela não tem acesso.
  • Não execute ações no Dashboard enquanto estiver conectado como uma função de usuário que não tenha permissão.

Erros de limitação de fluxo

Tipo

StripeRateLimitError

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.
  • Para gerenciar automaticamente a limitação de taxa, repita a chamada da API após um intervalo e aumente exponencialmente esse atraso se o erro continuar. Consulte a documentação sobre limitações de taxa para obter mais orientações.
  • 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

StripeSignatureVerificationError

ProblemaVocê está usando verificação de assinatura de webhooks e não conseguiu verificar a autenticidade de um evento de webhook.

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.

Se este erro ocorrer de forma inesperada (por exemplo, com webhooks que você sabe que são originados com Stripe), consulte a documentação sobre verificação de assinaturas de webhooks para obter mais orientações. Especificamente, verifique se está usando o segredo de endpoint correto. Isso é diferente da sua chave da API.

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