# Visão geral dos erros da API

Payments Direct retorna respostas de erro padronizadas em todas as operações da sua API, o que facilita registrar, monitorar e diagnosticar problemas de integração.

Os endpoints de token OAuth são a exceção. Eles seguem o formato de erro do OAuth 2.0, descrito em [Erros de autenticação](/pt-br/products/payments-direct-2/api-docs/get-started/authentication#erros-de-autentica%C3%A7%C3%A3o).

## Schema do corpo da resposta de erro

Com exceção dos endpoints de token OAuth, toda resposta de erro tem a mesma estrutura: um `status` de nível superior e um array `errors` contendo um ou mais objetos de erro.

| Campo | Tipo | Descrição |
|  --- | --- | --- |
| `status` | integer | O código de status HTTP da resposta. |
| `errors` | array | Um ou mais objetos de erro que descrevem o que deu errado. Uma única requisição pode falhar por mais de um motivo. |


Cada objeto do array `errors` contém os seguintes campos:

| Campo | Tipo | Descrição |
|  --- | --- | --- |
| `code` | string | Um identificador único do erro (por exemplo, `USR_067`). |
| `type` | string | A categoria do erro. Um de: `AUTH_ERROR`, `USER_ERROR`, `NOT_FOUND`, `CONFIGURATION_ERROR`, `SYSTEM_ERROR`. |
| `title` | string | Um resumo curto e legível do erro. |
| `description` | string | Uma explicação concisa do erro. Pode incluir instruções de recuperação. |
| `timestamp` | string (ISO 8601) | O momento em que o erro ocorreu. |


Onde ler o status HTTP
O `status` aparece uma única vez, no nível superior da resposta. Ele não é um campo dos objetos de erro individuais. Sempre percorra `errors` como um array, mesmo quando ele contiver uma única entrada.

## Exemplo de resposta de erro

```json
{
  "status": 402,
  "errors": [
    {
      "code": "USR_067",
      "type": "USER_ERROR",
      "title": "Insufficient balance",
      "description": "Payment failed due to insufficient balance. Add funds to your account and try again.",
      "timestamp": "2025-08-21T10:15:30Z"
    }
  ]
}
```

## Tratando erros da API

Ao construir a sua integração:

* Sempre **registre e monitore** os campos `code` e `status` em todas as respostas de erro.
* **Verifique primeiro o código do erro** ao decidir como tratá-lo. Não dependa apenas do código de status HTTP.
* Trate o campo `description` como orientação para pessoas, não como lógica programática. O texto dele pode mudar entre versões.


### Erros transitórios vs. permanentes

Alguns erros são transitórios e permitem nova tentativa; outros indicam uma condição que precisa ser resolvida antes do reenvio.

| Tipo de erro | Status HTTP | Tentar novamente? | 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, limites ou dados de identidade) antes de tentar novamente. |
| `NOT_FOUND` | 404 | Não | Verifique o ID do recurso e reenvie. |
| `AUTH_ERROR` | 401 | Após renovar o token | Gere um novo token de acesso e tente novamente. |
| `AUTH_ERROR` | 403 | Não | Verifique se o seu token tem os escopos necessários para esta ação. Em operações de pagamento, um `403` também pode significar que o pagamento existe, mas pertence a outro tenant. |
| `SYSTEM_ERROR` | 500 | Sim, com backoff | 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. |


Para a lista completa de códigos de erro, consulte a referência [Erros da API](/pt-br/products/payments-direct-2/api-docs/error-handling/api-errors).

Para orientações sobre estratégia de nova tentativa, backoff exponencial e monitoramento, consulte [Tratamento de erros e estratégia de nova tentativa](/pt-br/products/payments-direct-2/api-docs/error-handling).