{"templateId":"markdown","versions":[{"version":"v2026.04","label":"v2026.04","link":"/pt-br/products/payments-direct-2/api-docs/error-handling","default":true,"active":true,"folderId":"7e5507fe"},{"version":"v2026.03","label":"v2026.03","link":"/pt-br/products/payments-direct-2/v2026.03/api-docs/error-handling","default":false,"active":false,"folderId":"7e5507fe"},{"version":"v2025.11","label":"v2025.11","link":"/pt-br/products/payments-direct-2/v2025.11/api-docs/error-handling","default":false,"active":false,"folderId":"7e5507fe"}],"sharedDataIds":{"sidebar":"sidebar-@l10n/pt-BR/products/payments-direct-2/@v2025.11/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Tratamento de erros e estratégia de novas tentativas","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"tratamento-de-erros-e-estratégia-de-novas-tentativas","__idx":0},"children":["Tratamento de erros e estratégia de novas tentativas"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payments Direct"," retorna uma ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/api-docs/error-handling/payments-direct-api-errors"},"children":["resposta de erro padronizada"]}," para toda requisição de API que falha. Construir uma integração confiável significa classificar os erros corretamente, tentar novamente com segurança e escalar rapidamente quando tentar novamente não resolver."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Este tópico aborda:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Como classificar erros usando os campos ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," e ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Quais erros podem ser repetidos com segurança e como repeti-los"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Parâmetros recomendados de espera exponencial"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Tratamento de erros de autenticação"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Tratamento de falhas de pagamento (estados FAILED, DECLINED, RETURNED)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["O que registrar e monitorar"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"classifique-antes-de-agir","__idx":1},"children":["Classifique antes de agir"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Toda resposta de erro inclui um campo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," (por exemplo, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USR_067"]},") e um campo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," (por exemplo, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USER_ERROR"]},"). Use sempre o campo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," como sinal principal, e não apenas o código de status HTTP. Dois erros podem compartilhar o mesmo status HTTP e exigir tratamentos completamente diferentes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"referência-de-tipos-de-erro","__idx":2},"children":["Referência de tipos de erro"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Tipo"},"children":["Tipo"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Prefixo"},"children":["Prefixo"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"O que significa"},"children":["O que significa"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Ação geral"},"children":["Ação geral"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USER_ERROR"]}," ou ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOT_FOUND"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USR_"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["O problema é a própria requisição: campos ausentes, valores inválidos ou um recurso que não existe."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Corrija a requisição e reenvie. Não repita a mesma requisição."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH_"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A requisição foi rejeitada por um problema de autenticação ou autorização."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#tratamento-de-erros-de-autentica%C3%A7%C3%A3o"},"children":["Tratamento de erros de autenticação"]}," abaixo."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYSTEM_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYS_"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ocorreu um erro interno na infraestrutura da Ripple."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tente novamente com espera exponencial. Escale para o suporte técnico da Ripple se a condição persistir."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONFIGURATION_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CFG_"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Um problema de configuração de conta ou de serviço impede a conclusão da requisição."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Não tente novamente. Entre em contato com o suporte técnico da Ripple."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"erros-transitórios-vs-permanentes","__idx":3},"children":["Erros transitórios vs. permanentes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Antes de repetir, confirme que o erro é transitório (uma condição que pode se resolver sozinha) e não permanente."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Tipo de erro"},"children":["Tipo de erro"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status HTTP"},"children":["Status HTTP"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Pode repetir?"},"children":["Pode repetir?"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Ação recomendada"},"children":["Ação recomendada"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USER_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400, 404, 415"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Não"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Corrija a requisição e reenvie."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USER_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["402"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Não até ser resolvido"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Resolva a condição subjacente (saldo insuficiente, limite de crédito ou fatura vencida) antes de tentar novamente."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOT_FOUND"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["404"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Não"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verifique o ID do recurso e reenvie."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["401"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sim (após renovar o token)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Gere um novo token de acesso e tente novamente."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["403"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Não"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Confirme que o seu token tem os escopos necessários. Entre em contato com o suporte técnico da Ripple se o problema persistir."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYSTEM_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sim (com espera)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tente novamente com espera exponencial. Entre em contato com o suporte técnico da Ripple se o problema persistir."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONFIGURATION_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Não"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Entre em contato com o suporte técnico da Ripple."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"estratégia-de-novas-tentativas","__idx":4},"children":["Estratégia de novas tentativas"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"espera-exponencial-com-jitter","__idx":5},"children":["Espera exponencial com jitter"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Quando uma requisição falha com um erro que pode ser repetido (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYSTEM_ERROR"]}," / 500, ou ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH_ERROR"]}," / 401 após a renovação do token), use backoff exponencial com jitter em vez de repetir imediatamente ou em intervalos fixos. Novas tentativas imediatas ou sincronizadas amplificam a carga em um sistema já sobrecarregado e podem acionar a limitação de taxa."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Abordagem recomendada:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Na primeira falha, aguarde um intervalo base curto."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A cada falha seguinte, dobre o tempo de espera."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Adicione jitter aleatório (±10–20% do intervalo) para dessincronizar as novas tentativas entre os clientes."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Limite a espera máxima a um teto razoável."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Após um número configurável de tentativas, pare de repetir e alerte sua equipe de plantão."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Exemplo de escalonamento de espera:"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Tentativa"},"children":["Tentativa"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Espera base"},"children":["Espera base"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Com jitter (±20%)"},"children":["Com jitter (±20%)"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["1"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2s"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["1,6s – 2,4s"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["4s"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3,2s – 4,8s"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["8s"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["6,4s – 9,6s"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["4"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["16s"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["12,8s – 19,2s"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["5"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["32s"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["25,6s – 38,4s"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["6+"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["60s (limite)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["48s – 72s"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-um-número-máximo-de-novas-tentativas","__idx":6},"children":["Use um número máximo de novas tentativas"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Defina um limite rígido para o número de novas tentativas (por exemplo, 5 tentativas). Depois que esse limite for atingido sem uma resposta bem-sucedida, pare de repetir, registre a falha e alerte sua equipe. Continuar repetindo indefinidamente pode mascarar um problema persistente e atrasar a investigação."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"idempotência-e-novas-tentativas-seguras","__idx":7},"children":["Idempotência e novas tentativas seguras"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Um timeout ou erro de conexão em uma requisição de criação de pagamento não significa que o pagamento não foi criado. A Ripple pode ter recebido e processado a requisição mesmo que você não tenha recebido a resposta."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"o-quoteid-é-a-chave-de-idempotência","__idx":8},"children":["O ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quoteId"]}," é a chave de idempotência"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A criação de pagamentos é deduplicada por ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quoteId"]},", e uma cotação pode produzir no máximo um pagamento. Se já existir um pagamento para o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quoteId"]}," em uma requisição ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v3/payments"]},", a Ripple retorna esse pagamento em vez de criar um novo."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Quando você reenvia uma requisição para uma cotação que já tem um pagamento:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A resposta é ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]},", a mesma de um novo pagamento. O código de status não informa se esta requisição criou o pagamento ou retornou um já existente."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["O pagamento é retornado como foi armazenado. A Ripple não compara o restante do corpo da requisição com ele, portanto alterar um campo em um reenvio não tem efeito. Reenvie a requisição original sem alterações."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["O pagamento é retornado mesmo que a cotação tenha expirado desde a primeira requisição."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," não é uma chave de idempotência para pagamentos. A Ripple não verifica a unicidade dos valores de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," de pagamento, portanto duas requisições com o mesmo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," e valores diferentes de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quoteId"]}," criam dois pagamentos. Isso difere das identidades, onde o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," precisa ser único entre as suas identidades ACTIVE. Consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/concepts/payment-identities#idempot%C3%AAncia-e-deduplica%C3%A7%C3%A3o-com-internalid"},"children":["Identidades do pagamento"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"repetindo-após-um-timeout","__idx":9},"children":["Repetindo após um timeout"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Repita com o mesmo quoteId, nunca com uma nova cotação"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se uma requisição de criação de pagamento expirar ou falhar com um erro de conexão, reenvie-a com o mesmo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quoteId"]},". Se a primeira requisição criou o pagamento, o reenvio o retorna. Se não criou, o reenvio o cria."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Não obtenha uma nova cotação e a envie no lugar da primeira. Um novo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quoteId"]}," é um novo pagamento, e a Ripple não tem como saber que ele duplica o primeiro, mesmo que as duas requisições tenham o mesmo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Espace os reenvios usando o backoff descrito em ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#estrat%C3%A9gia-de-novas-tentativas"},"children":["Retry strategy"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se um reenvio for rejeitado com HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," e ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USR_058"]}," (cotação expirada), nenhum pagamento estava armazenado para essa cotação quando o reenvio foi processado. Antes de obter uma nova cotação, verifique se a requisição original não criou um pagamento, conforme descrito abaixo."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"verificando-se-um-pagamento-foi-criado","__idx":10},"children":["Verificando se um pagamento foi criado"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Para conciliar pagamentos com os seus próprios registros, faça a busca com ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v3/payments/filter"]}," e o seu ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]},". Essa continua sendo uma verificação válida, com dois limites:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Os resultados da busca são atualizados de forma assíncrona. Um pagamento criado há instantes pode ainda não aparecer, portanto um resultado vazio logo após um timeout não prova que o pagamento não foi criado."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["O filtro de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," não é uma busca por correspondência exata. Confirme que o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," de cada pagamento retornado corresponde exatamente ao seu."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Por causa desses limites, reenviar com o mesmo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quoteId"]}," é a maneira confiável de se recuperar de um timeout. Use a busca para conciliar, não para decidir se deve reenviar."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tratamento-de-erros-de-autenticação","__idx":11},"children":["Tratamento de erros de autenticação"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"401-unauthorized-auth_001-auth_003","__idx":12},"children":["401 Unauthorized (AUTH_001, AUTH_003)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Um erro 401 normalmente significa que o seu token de acesso expirou ou é inválido. Os tokens de acesso têm TTL de 1 hora."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Tratamento recomendado:"]}]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Gere um novo token de acesso usando o seu ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," e o seu ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Repita a requisição original com o novo token."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Não armazene tokens em cache além do valor de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_in"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Para orientações sobre geração e cache de tokens, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/api-docs/get-started/authentication"},"children":["Autenticação"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"403-forbidden-auth_002","__idx":13},"children":["403 Forbidden (AUTH_002)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Um erro 403 significa que o seu token é válido, mas não tem os escopos necessários para a operação solicitada."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Tratamento recomendado:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Não repita com o mesmo token. Um novo token com as mesmas credenciais terá os mesmos escopos."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Revise os escopos exigidos pela operação na referência da API."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Entre em contato com o suporte técnico da Ripple se acreditar que as suas credenciais deveriam ter as permissões necessárias."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"403-unauthorized-auth_051","__idx":14},"children":["403 Unauthorized (AUTH_051)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O AUTH_051 ocorre quando uma requisição referencia um pagamento criado por outra organização. Este é um erro permanente. Não tente novamente."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tratamento-de-falhas-de-pagamento","__idx":15},"children":["Tratamento de falhas de pagamento"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As falhas de pagamento são diferentes dos erros de API. Uma falha de pagamento ocorre depois que um pagamento é criado com sucesso (HTTP 201) mas passa, mais tarde, para um estado terminal de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]}," ou ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURNED"]},". Elas não são erros na resposta da API. São valores de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentState"]}," que você observa ao fazer polling ou ao receber webhooks."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Como detectar uma falha de pagamento"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Os detalhes da falha de pagamento, incluindo o código e o motivo do erro, ficam disponíveis no objeto do pagamento em ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/payments/{paymentId}"]}," depois que o pagamento chega a um estado terminal. Os payloads de webhook incluem o novo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentState"]},", mas não o código de erro. Busque sempre o registro completo do pagamento para obter os detalhes da falha."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"estados-terminais","__idx":16},"children":["Estados terminais"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Estado"},"children":["Estado"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Pode repetir?"},"children":["Pode repetir?"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Ação"},"children":["Ação"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Possivelmente"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Busque o registro do pagamento para obter o código de erro. Consulte a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/api-docs/error-handling/api-payment-failures"},"children":["Falhas de pagamento da API"]}," e a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/api-docs/error-handling/api-errors"},"children":["Erros da API"]}," para o código específico. Alguns estados ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}," são causados por problemas transitórios e podem ser repetidos com um novo pagamento; outros indicam uma condição permanente."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Não até ser resolvido"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Busque o registro do pagamento para obter o código de erro. O ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]}," normalmente indica uma violação de regra de negócio ou uma condição da conta (saldo insuficiente, limite de crédito etc.) que precisa ser resolvida antes de reenviar."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURNED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Consulte a Ripple"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["O pagamento foi devolvido por uma instituição downstream após ser concluído. Este não é um cenário de nova tentativa. Entre em contato com o suporte técnico da Ripple para investigar o motivo da devolução."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Para ver a lista completa de códigos de falha de pagamento e as descrições deles, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/api-docs/error-handling/api-payment-failures"},"children":["Falhas de pagamento da API"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Para entender os estados do pagamento e o ciclo de vida do pagamento, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/concepts/payment-lifecycle"},"children":["Ciclo de vida do pagamento"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"o-que-registrar-e-monitorar","__idx":17},"children":["O que registrar e monitorar"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Registre os seguintes campos de toda resposta de erro:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," — o código de erro específico; use-o em regras de alerta e dashboards"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," — a categoria do erro; use-a para encaminhar ao handler correto"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," — o código de status HTTP"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timestamp"]}," — o momento em que o erro ocorreu no sistema upstream"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["O endpoint da API e o método HTTP que retornaram o erro"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["O seu ID de requisição ou ID de correlação (se a sua integração gerar um)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"recomendações-de-alerta","__idx":18},"children":["Recomendações de alerta"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Condição"},"children":["Condição"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Prioridade do alerta"},"children":["Prioridade do alerta"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Qualquer ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONFIGURATION_ERROR"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CFG_"]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Alta — exigem o envolvimento da Ripple e não se resolvem sozinhos"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYSTEM_ERROR"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYS_"]},") repetidos do mesmo endpoint"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Média: investigue após esgotar o orçamento de novas tentativas"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH_ERROR"]}," 403 (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH_002"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH_051"]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Média — pode indicar uma mudança de configuração ou um problema de escopo das credenciais"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USER_ERROR"]}," 402 (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USR_062"]},"–",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USR_067"]},") contínuos"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Média — indica uma condição da conta (saldo, limites, fatura) que exige atenção"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"próximos-passos","__idx":19},"children":["Próximos passos"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Para ver a lista completa de códigos de erro, descrições e status HTTP, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/api-docs/error-handling/api-errors"},"children":["Erros da API"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Para ver os códigos de falha específicos de pagamento, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/api-docs/error-handling/api-payment-failures"},"children":["Falhas de pagamento da API"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Para orientações sobre como acompanhar as mudanças de estado do pagamento sem polling, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/api-docs/payment-monitoring/notification-webhooks"},"children":["Webhooks de notificação"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Para fazer polling de atualizações de pagamento em vez de usar webhooks, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/api-docs/payment-monitoring/polling"},"children":["Polling"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Para detalhes sobre a geração e o cache de tokens de acesso, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/api-docs/get-started/authentication"},"children":["Autenticação"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Para ver as definições dos estados do pagamento e os detalhes do ciclo de vida, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/concepts/payment-lifecycle"},"children":["Ciclo de vida do pagamento"]},"."]}]}]},"headings":[{"value":"Tratamento de erros e estratégia de novas tentativas","id":"tratamento-de-erros-e-estratégia-de-novas-tentativas","depth":1},{"value":"Classifique antes de agir","id":"classifique-antes-de-agir","depth":2},{"value":"Referência de tipos de erro","id":"referência-de-tipos-de-erro","depth":3},{"value":"Erros transitórios vs. permanentes","id":"erros-transitórios-vs-permanentes","depth":2},{"value":"Estratégia de novas tentativas","id":"estratégia-de-novas-tentativas","depth":2},{"value":"Espera exponencial com jitter","id":"espera-exponencial-com-jitter","depth":3},{"value":"Use um número máximo de novas tentativas","id":"use-um-número-máximo-de-novas-tentativas","depth":3},{"value":"Idempotência e novas tentativas seguras","id":"idempotência-e-novas-tentativas-seguras","depth":2},{"value":"O quoteId é a chave de idempotência","id":"o-quoteid-é-a-chave-de-idempotência","depth":3},{"value":"Repetindo após um timeout","id":"repetindo-após-um-timeout","depth":3},{"value":"Verificando se um pagamento foi criado","id":"verificando-se-um-pagamento-foi-criado","depth":3},{"value":"Tratamento de erros de autenticação","id":"tratamento-de-erros-de-autenticação","depth":2},{"value":"401 Unauthorized (AUTH_001, AUTH_003)","id":"401-unauthorized-auth_001-auth_003","depth":3},{"value":"403 Forbidden (AUTH_002)","id":"403-forbidden-auth_002","depth":3},{"value":"403 Unauthorized (AUTH_051)","id":"403-unauthorized-auth_051","depth":3},{"value":"Tratamento de falhas de pagamento","id":"tratamento-de-falhas-de-pagamento","depth":2},{"value":"Estados terminais","id":"estados-terminais","depth":3},{"value":"O que registrar e monitorar","id":"o-que-registrar-e-monitorar","depth":2},{"value":"Recomendações de alerta","id":"recomendações-de-alerta","depth":3},{"value":"Próximos passos","id":"próximos-passos","depth":2}],"frontmatter":{"seo":{"title":"Tratamento de erros e estratégia de novas tentativas"}},"lastModified":"2026-10-21T01:29:12.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/pt-br/products/payments-direct-2/api-docs/error-handling","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}