# Tratamento de erros e estratégia de nova tentativa

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 permitem nova tentativa com segurança e como fazê-la
- 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 tentar novamente, confirme se o erro é transitório (uma condição que pode se resolver sozinha) e não permanente.

| Tipo de erro | Status HTTP | Permite nova tentativa? | 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 nova tentativa

### Espera exponencial com jitter

Quando uma requisição falha com um erro que permite nova tentativa (`SYSTEM_ERROR` / 500, ou `AUTH_ERROR` / 401 após a renovação do token), use espera exponencial com jitter em vez de tentar novamente imediatamente ou em intervalos fixos. Novas tentativas imediatas ou sincronizadas ampliam 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 um jitter aleatório (±10 a 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 tentar novamente e acione a 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). Quando esse limite for atingido sem uma resposta bem-sucedida, pare de tentar novamente, registre a falha e acione a sua equipe. Continuar tentando novamente indefinidamente pode mascarar um problema persistente e atrasar a investigação.

## Idempotência e novas tentativas seguras

Antes de tentar novamente uma requisição que altera dados (como a criação de um pagamento), verifique se a requisição original pode ter sido recebida e processada pela Ripple apesar de ter retornado um erro. Um timeout de rede, por exemplo, não significa que o pagamento não foi criado.

**Boa prática:** use um `internalId` atribuído pelo cliente ou um mecanismo de idempotência ao criar pagamentos. Se você tentar novamente uma requisição de criação de pagamento, inclua o mesmo `internalId` da requisição original. A Ripple retornará o pagamento existente, caso ele já tenha sido criado, evitando pagamentos duplicados.

Não repita a criação de pagamentos às cegas
Se você receber um timeout ou erro de conexão em uma requisição de criação de pagamento, não repita imediatamente sem antes verificar se o pagamento foi criado. Use `GET /v3/payments` com o seu `internalId` para verificar antes de enviar novamente.

## 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 | Permite nova tentativa? | Ação |
|  --- | --- | --- |
| `FAILED` | Possivelmente | Busque o registro do pagamento para obter o código de erro. Consulte a [referência de falhas de pagamento da API](/pt-br/products/payments-direct-2/api-docs/error-handling/api-payment-failures) e a [referência de códigos de erro da API](/pt-br/products/payments-direct-2/api-docs/error-handling/api-errors) para ver o código específico. Alguns estados `FAILED` são causados por problemas transitórios e permitem nova tentativa 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 depois de 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 depois de 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).