Tratamento de erros e estratégia de novas tentativas

Payments Direct retorna uma 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.

Este tópico aborda:

• Como classificar erros usando os campos code e type
• Quais erros podem ser repetidos com segurança e como repeti-los
• Parâmetros recomendados de espera exponencial
• Tratamento de erros de autenticação
• Tratamento de falhas de pagamento (estados FAILED, DECLINED, RETURNED)
• O que registrar e monitorar

Toda resposta de erro inclui um campo code (por exemplo, USR_067) e um campo type (por exemplo, USER_ERROR). Use sempre o campo 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.

Antes de repetir, confirme que o erro é transitório (uma condição que pode se resolver sozinha) e não permanente.

Quando uma requisição falha com um erro que pode ser repetido (SYSTEM_ERROR / 500, ou 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.

Abordagem recomendada:

1. Na primeira falha, aguarde um intervalo base curto.
2. A cada falha seguinte, dobre o tempo de espera.
3. Adicione jitter aleatório (±10–20% do intervalo) para dessincronizar as novas tentativas entre os clientes.
4. Limite a espera máxima a um teto razoável.
5. Após um número configurável de tentativas, pare de repetir e alerte sua equipe de plantão.

Exemplo de escalonamento de espera:

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.

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.

A criação de pagamentos é deduplicada por quoteId, e uma cotação pode produzir no máximo um pagamento. Se já existir um pagamento para o quoteId em uma requisição POST /v3/payments, a Ripple retorna esse pagamento em vez de criar um novo.

Quando você reenvia uma requisição para uma cotação que já tem um pagamento:

• A resposta é 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.
• 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.
• O pagamento é retornado mesmo que a cotação tenha expirado desde a primeira requisição.

O internalId não é uma chave de idempotência para pagamentos. A Ripple não verifica a unicidade dos valores de internalId de pagamento, portanto duas requisições com o mesmo internalId e valores diferentes de quoteId criam dois pagamentos. Isso difere das identidades, onde o internalId precisa ser único entre as suas identidades ACTIVE. Consulte Identidades do pagamento.

Espace os reenvios usando o backoff descrito em Retry strategy.

Se um reenvio for rejeitado com HTTP 400 e 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.

Para conciliar pagamentos com os seus próprios registros, faça a busca com POST /v3/payments/filter e o seu internalId. Essa continua sendo uma verificação válida, com dois limites:

• 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.
• O filtro de internalId não é uma busca por correspondência exata. Confirme que o internalId de cada pagamento retornado corresponde exatamente ao seu.

Por causa desses limites, reenviar com o mesmo quoteId é a maneira confiável de se recuperar de um timeout. Use a busca para conciliar, não para decidir se deve reenviar.

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.

Tratamento recomendado:

1. Gere um novo token de acesso usando o seu client_id e o seu client_secret.
2. Repita a requisição original com o novo token.
3. Não armazene tokens em cache além do valor de expires_in.

Para orientações sobre geração e cache de tokens, consulte Autenticação.

Um erro 403 significa que o seu token é válido, mas não tem os escopos necessários para a operação solicitada.

Tratamento recomendado:

• Não repita com o mesmo token. Um novo token com as mesmas credenciais terá os mesmos escopos.
• Revise os escopos exigidos pela operação na referência da API.
• Entre em contato com o suporte técnico da Ripple se acreditar que as suas credenciais deveriam ter as permissões necessárias.

O AUTH_051 ocorre quando uma requisição referencia um pagamento criado por outra organização. Este é um erro permanente. Não tente novamente.

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 FAILED, DECLINED ou RETURNED. Elas não são erros na resposta da API. São valores de paymentState que você observa ao fazer polling ou ao receber webhooks.

Para ver a lista completa de códigos de falha de pagamento e as descrições deles, consulte Falhas de pagamento da API.

Para entender os estados do pagamento e o ciclo de vida do pagamento, consulte Ciclo de vida do pagamento.

Registre os seguintes campos de toda resposta de erro:

• code — o código de erro específico; use-o em regras de alerta e dashboards
• type — a categoria do erro; use-a para encaminhar ao handler correto
• status — o código de status HTTP
• timestamp — o momento em que o erro ocorreu no sistema upstream
• O endpoint da API e o método HTTP que retornaram o erro
• O seu ID de requisição ou ID de correlação (se a sua integração gerar um)

• Para ver a lista completa de códigos de erro, descrições e status HTTP, consulte Erros da API.
• Para ver os códigos de falha específicos de pagamento, consulte Falhas de pagamento da API.
• Para orientações sobre como acompanhar as mudanças de estado do pagamento sem polling, consulte Webhooks de notificação.
• Para fazer polling de atualizações de pagamento em vez de usar webhooks, consulte Polling.
• Para detalhes sobre a geração e o cache de tokens de acesso, consulte Autenticação.
• Para ver as definições dos estados do pagamento e os detalhes do ciclo de vida, consulte Ciclo de vida do pagamento.