# Tratamento de erros e estratégia de novas tentativas

Payments Direct retorna uma [resposta de erro padronizada](/pt-br/products/payments-direct-2/api-docs/error-handling/payments-direct-api-errors) 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


## Classifique antes de agir

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.

### Referência de tipos de erro

| Tipo | Prefixo | O que significa | Ação geral |
|  --- | --- | --- | --- |
| `USER_ERROR` ou `NOT_FOUND` | `USR_` | O problema é a própria requisição: campos ausentes, valores inválidos ou um recurso que não existe. | Corrija a requisição e reenvie. Não repita a mesma requisição. |
| `AUTH_ERROR` | `AUTH_` | A requisição foi rejeitada por um problema de autenticação ou autorização. | Consulte [Tratamento de erros de autenticação](#tratamento-de-erros-de-autentica%C3%A7%C3%A3o) abaixo. |
| `SYSTEM_ERROR` | `SYS_` | Ocorreu um erro interno na infraestrutura da Ripple. | Tente novamente com espera exponencial. Escale para o suporte técnico da Ripple se a condição persistir. |
| `CONFIGURATION_ERROR` | `CFG_` | Um problema de configuração de conta ou de serviço impede a conclusão da requisição. | Não tente novamente. Entre em contato com o suporte técnico da Ripple. |


## Erros transitórios vs. permanentes

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

| Tipo de erro | Status HTTP | Pode repetir? | Ação recomendada |
|  --- | --- | --- | --- |
| `USER_ERROR` | 400, 404, 415 | Não | Corrija a requisição e reenvie. |
| `USER_ERROR` | 402 | Não até ser resolvido | Resolva a condição subjacente (saldo insuficiente, limite de crédito ou fatura vencida) antes de tentar novamente. |
| `NOT_FOUND` | 404 | Não | Verifique o ID do recurso e reenvie. |
| `AUTH_ERROR` | 401 | Sim (após renovar o token) | Gere um novo token de acesso e tente novamente. |
| `AUTH_ERROR` | 403 | Não | Confirme que o seu token tem os escopos necessários. Entre em contato com o suporte técnico da Ripple se o problema persistir. |
| `SYSTEM_ERROR` | 500 | Sim (com espera) | Tente novamente com espera exponencial. Entre em contato com o suporte técnico da Ripple se o problema persistir. |
| `CONFIGURATION_ERROR` | 500 | Não | Entre em contato com o suporte técnico da Ripple. |


## Estratégia de novas tentativas

### Espera exponencial com jitter

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:**

| Tentativa | Espera base | Com jitter (±20%) |
|  --- | --- | --- |
| 1 | 2s | 1,6s – 2,4s |
| 2 | 4s | 3,2s – 4,8s |
| 3 | 8s | 6,4s – 9,6s |
| 4 | 16s | 12,8s – 19,2s |
| 5 | 32s | 25,6s – 38,4s |
| 6+ | 60s (limite) | 48s – 72s |


### Use um número máximo de novas tentativas

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.

## Idempotência e novas tentativas seguras

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.

### O `quoteId` é a chave de idempotência

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](/pt-br/products/payments-direct-2/introduction/concepts/payment-identities#idempot%C3%AAncia-e-deduplica%C3%A7%C3%A3o-com-internalid).

### Repetindo após um timeout

Repita com o mesmo quoteId, nunca com uma nova cotação
Se uma requisição de criação de pagamento expirar ou falhar com um erro de conexão, reenvie-a com o mesmo `quoteId`. Se a primeira requisição criou o pagamento, o reenvio o retorna. Se não criou, o reenvio o cria.

Não obtenha uma nova cotação e a envie no lugar da primeira. Um novo `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 `internalId`.

Espace os reenvios usando o backoff descrito em [Retry strategy](#estrat%C3%A9gia-de-novas-tentativas).

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.

### Verificando se um pagamento foi criado

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.

## Tratamento de erros de autenticação

### 401 Unauthorized (AUTH_001, AUTH_003)

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](/pt-br/products/payments-direct-2/api-docs/get-started/authentication).

### 403 Forbidden (AUTH_002)

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.


### 403 Unauthorized (AUTH_051)

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

## Tratamento de falhas de pagamento

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.

Como detectar uma falha de pagamento
Os detalhes da falha de pagamento, incluindo o código e o motivo do erro, ficam disponíveis no objeto do pagamento em `GET /v3/payments/{paymentId}` depois que o pagamento chega a um estado terminal. Os payloads de webhook incluem o novo `paymentState`, mas não o código de erro. Busque sempre o registro completo do pagamento para obter os detalhes da falha.

### Estados terminais

| Estado | Pode repetir? | Ação |
|  --- | --- | --- |
| `FAILED` | Possivelmente | Busque o registro do pagamento para obter o código de erro. Consulte a [Falhas de pagamento da API](/pt-br/products/payments-direct-2/api-docs/error-handling/api-payment-failures) e a [Erros da API](/pt-br/products/payments-direct-2/api-docs/error-handling/api-errors) para o código específico. Alguns estados `FAILED` são causados por problemas transitórios e podem ser repetidos com um novo pagamento; outros indicam uma condição permanente. |
| `DECLINED` | Não até ser resolvido | Busque o registro do pagamento para obter o código de erro. O `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. |
| `RETURNED` | Consulte a Ripple | 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. |


Para ver a lista completa de códigos de falha de pagamento e as descrições deles, consulte [Falhas de pagamento da API](/pt-br/products/payments-direct-2/api-docs/error-handling/api-payment-failures).

Para entender os estados do pagamento e o ciclo de vida do pagamento, consulte [Ciclo de vida do pagamento](/pt-br/products/payments-direct-2/introduction/concepts/payment-lifecycle).

## O que registrar e monitorar

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)


### Recomendações de alerta

| Condição | Prioridade do alerta |
|  --- | --- |
| Qualquer `CONFIGURATION_ERROR` (`CFG_`) | Alta — exigem o envolvimento da Ripple e não se resolvem sozinhos |
| `SYSTEM_ERROR` (`SYS_`) repetidos do mesmo endpoint | Média: investigue após esgotar o orçamento de novas tentativas |
| `AUTH_ERROR` 403 (`AUTH_002`, `AUTH_051`) | Média — pode indicar uma mudança de configuração ou um problema de escopo das credenciais |
| `USER_ERROR` 402 (`USR_062`–`USR_067`) contínuos | Média — indica uma condição da conta (saldo, limites, fatura) que exige atenção |


## Próximos passos

- Para ver a lista completa de códigos de erro, descrições e status HTTP, consulte [Erros da API](/pt-br/products/payments-direct-2/api-docs/error-handling/api-errors).
- Para ver os códigos de falha específicos de pagamento, consulte [Falhas de pagamento da API](/pt-br/products/payments-direct-2/api-docs/error-handling/api-payment-failures).
- Para orientações sobre como acompanhar as mudanças de estado do pagamento sem polling, consulte [Webhooks de notificação](/pt-br/products/payments-direct-2/api-docs/payment-monitoring/notification-webhooks).
- Para fazer polling de atualizações de pagamento em vez de usar webhooks, consulte [Polling](/pt-br/products/payments-direct-2/api-docs/payment-monitoring/polling).
- Para detalhes sobre a geração e o cache de tokens de acesso, consulte [Autenticação](/pt-br/products/payments-direct-2/api-docs/get-started/authentication).
- Para ver as definições dos estados do pagamento e os detalhes do ciclo de vida, consulte [Ciclo de vida do pagamento](/pt-br/products/payments-direct-2/introduction/concepts/payment-lifecycle).