{"templateId":"markdown","versions":[{"version":"v2026.04","label":"v2026.04","link":"/pt-br/products/payments-direct-2/api-docs/error-handling/payments-direct-api-errors","default":true,"active":true,"folderId":"7e5507fe"},{"version":"v2026.03","label":"v2026.03","link":"/pt-br/products/payments-direct-2/v2026.03/api-docs/error-handling/payments-direct-api-errors","default":false,"active":false,"folderId":"7e5507fe"},{"version":"v2025.11","label":"v2025.11","link":"/pt-br/products/payments-direct-2/v2025.11/api-docs/error-handling/payments-direct-api-errors","default":false,"active":false,"folderId":"7e5507fe"}],"sharedDataIds":{"sidebar":"sidebar-@l10n/pt-BR/products/payments-direct-2/@v2025.11/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Visão geral dos erros da API","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"visão-geral-dos-erros-da-api","__idx":0},"children":["Visão geral dos erros da API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Os endpoints de token OAuth são a exceção. Eles seguem o formato de erro do OAuth 2.0, descrito em ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/api-docs/get-started/authentication#erros-de-autentica%C3%A7%C3%A3o"},"children":["Erros de autenticação"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"schema-do-corpo-da-resposta-de-erro","__idx":1},"children":["Schema do corpo da resposta de erro"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Com exceção dos endpoints de token OAuth, toda resposta de erro tem a mesma estrutura: um ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," de nível superior e um array ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," contendo um ou mais objetos de erro."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Campo"},"children":["Campo"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Tipo"},"children":["Tipo"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Descrição"},"children":["Descrição"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["O código de status HTTP da resposta."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Um ou mais objetos de erro que descrevem o que deu errado. Uma única requisição pode falhar por mais de um motivo."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cada objeto do array ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," contém os seguintes campos:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Campo"},"children":["Campo"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Tipo"},"children":["Tipo"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Descrição"},"children":["Descrição"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Um identificador único do erro (por exemplo, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USR_067"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A categoria do erro. Um de: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH_ERROR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USER_ERROR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOT_FOUND"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONFIGURATION_ERROR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYSTEM_ERROR"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Um resumo curto e legível do erro."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Uma explicação concisa do erro. Pode incluir instruções de recuperação."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timestamp"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string (ISO 8601)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["O momento em que o erro ocorreu."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Onde ler o status HTTP"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," aparece uma única vez, no nível superior da resposta. Ele não é um campo dos objetos de erro individuais. Sempre percorra ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," como um array, mesmo quando ele contiver uma única entrada."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"exemplo-de-resposta-de-erro","__idx":2},"children":["Exemplo de resposta de erro"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"status\": 402,\n  \"errors\": [\n    {\n      \"code\": \"USR_067\",\n      \"type\": \"USER_ERROR\",\n      \"title\": \"Insufficient balance\",\n      \"description\": \"Payment failed due to insufficient balance. Add funds to your account and try again.\",\n      \"timestamp\": \"2025-08-21T10:15:30Z\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tratando-erros-da-api","__idx":3},"children":["Tratando erros da API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ao construir a sua integração:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sempre ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["registre e monitore"]}," os campos ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," e ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," em todas as respostas de erro."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verifique primeiro o código do erro"]}," ao decidir como tratá-lo. Não dependa apenas do código de status HTTP."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Trate o campo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}," como orientação para pessoas, não como lógica programática. O texto dele pode mudar entre versões."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"erros-transitórios-vs-permanentes","__idx":4},"children":["Erros transitórios vs. permanentes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Alguns erros são transitórios e permitem nova tentativa; outros indicam uma condição que precisa ser resolvida antes do reenvio."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Tipo de erro"},"children":["Tipo de erro"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status HTTP"},"children":["Status HTTP"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Tentar novamente?"},"children":["Tentar novamente?"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Ação recomendada"},"children":["Ação recomendada"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USER_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400, 404, 415"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Não"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Corrija a requisição e reenvie."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USER_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["402"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Não (até ser resolvido)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Resolva a condição subjacente (saldo, limites ou dados de identidade) antes de tentar novamente."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOT_FOUND"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["404"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Não"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verifique o ID do recurso e reenvie."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["401"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Após renovar o token"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Gere um novo token de acesso e tente novamente."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["403"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Não"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verifique se o seu token tem os escopos necessários para esta ação. Em operações de pagamento, um ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}," também pode significar que o pagamento existe, mas pertence a outro tenant."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYSTEM_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sim, com backoff"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tente novamente com espera exponencial. Entre em contato com o suporte técnico da Ripple se o problema persistir."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYSTEM_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["503"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sim, após o horário informado"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Há 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."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONFIGURATION_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Não"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Entre em contato com o suporte técnico da Ripple."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Para a lista completa de códigos de erro, consulte a referência ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/api-docs/error-handling/api-errors"},"children":["Erros da API"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Para orientações sobre estratégia de nova tentativa, backoff exponencial e monitoramento, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/api-docs/error-handling"},"children":["Tratamento de erros e estratégia de nova tentativa"]},"."]}]},"headings":[{"value":"Visão geral dos erros da API","id":"visão-geral-dos-erros-da-api","depth":1},{"value":"Schema do corpo da resposta de erro","id":"schema-do-corpo-da-resposta-de-erro","depth":2},{"value":"Exemplo de resposta de erro","id":"exemplo-de-resposta-de-erro","depth":2},{"value":"Tratando erros da API","id":"tratando-erros-da-api","depth":2},{"value":"Erros transitórios vs. permanentes","id":"erros-transitórios-vs-permanentes","depth":3}],"frontmatter":{"seo":{"title":"Visão geral dos erros da API"}},"lastModified":"2026-10-21T04:11:32.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/pt-br/products/payments-direct-2/api-docs/error-handling/payments-direct-api-errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}