Pular para o conteúdo

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.

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.

CampoTipoDescrição
statusintegerO código de status HTTP da resposta.
errorsarrayUm 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:

CampoTipoDescrição
codestringUm identificador único do erro (por exemplo, USR_067).
typestringA categoria do erro. Um de: AUTH_ERROR, USER_ERROR, NOT_FOUND, CONFIGURATION_ERROR, SYSTEM_ERROR.
titlestringUm resumo curto e legível do erro.
descriptionstringUma explicação concisa do erro. Pode incluir instruções de recuperação.
timestampstring (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

{
  "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 erroStatus HTTPTentar novamente?Ação recomendada
USER_ERROR400, 404, 415NãoCorrija a requisição e reenvie.
USER_ERROR402Não (até ser resolvido)Resolva a condição subjacente (saldo, limites ou dados de identidade) antes de tentar novamente.
NOT_FOUND404NãoVerifique o ID do recurso e reenvie.
AUTH_ERROR401Após renovar o tokenGere um novo token de acesso e tente novamente.
AUTH_ERROR403NãoVerifique 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_ERROR500Sim, com backoffTente novamente com espera exponencial. Entre em contato com o suporte técnico da Ripple se o problema persistir.
SYSTEM_ERROR503Sim, após o horário informadoHá uma janela de manutenção em vigor. A descrição do erro informa quando o serviço deve voltar. Tente novamente após esse horário, e não imediatamente.
CONFIGURATION_ERROR500NãoEntre 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.

Para orientações sobre estratégia de nova tentativa, backoff exponencial e monitoramento, consulte Tratamento de erros e estratégia de nova tentativa.

Erros da API

Payments Direct API