# Códigos de erro (/docs/conta-digital/error-codes) Toda recusa vem neste formato: ```json { "message": "Saldo insuficiente para este saque.", "code": "WITHDRAW_INSUFFICIENT_BALANCE", "details": { "available": 12500, "required": 20250 } } ``` | Campo | Descrição | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `message` | Texto em português, para exibir a quem usa o seu sistema. Pode mudar a qualquer momento, por isso as tabelas desta página não o repetem. | | `code` | Código estável, que não muda sem versão nova. É por ele que o seu sistema decide o que fazer. | | `details` | Contexto da recusa, quando existe. Pode não vir. | ## O que vem em `details` [#o-que-vem-em-details] * `SCHEMA_INVALID`: o campo com problema, no formato do corpo. Por exemplo, `{ "customer": { "document": "Informe um CPF ou CNPJ válido." } }`. * `REQUEST_UNKNOWN_QUERY_PARAM`: `details.unknownParams` traz os parâmetros de busca que a rota não conhece, e `details.accepted`, os que ela aceita. No corpo, campo desconhecido é ignorado. * `429`: `details.retryAfterSeconds`, o mesmo número de segundos do header `Retry-After`. * `PROVIDER_UNAVAILABLE` e `PROVIDER_REFUSED`: o status e o motivo devolvidos pelo banco, em `details.status` e `details.reason`. `details.status` vem `null` quando o banco não respondeu. ## Quando repetir [#quando-repetir] | Status | O que fazer | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400`, `404`, `409` | Não repita sem corrigir o pedido: a mesma chamada recebe a mesma recusa. | | `403`, `422` | Não repita igual. Algumas mudam com o estado da conta: `RECEIPT_MISSING_END_TO_END` (tente de novo em alguns minutos), `REFUND_IN_FLIGHT` (espere o resultado do estorno anterior), `*_INSUFFICIENT_BALANCE` (depois de entrar saldo), `*_DAILY_LIMIT` (no dia seguinte, horário de Brasília) e `TOKEN_HOLDER_BLOCKED` (quando o bloqueio sai). | | `401` | Não repita em laço. Gere um token novo ou corrija a credencial. | | `412` | Repita só depois de cumprir o passo que falta, indicado pelo `code`. `PAYMENT_CREATION_IN_FLIGHT` se resolve em instantes. | | `429` | Repita depois do tempo em `Retry-After`. | | `502` | A operação pode ter acontecido. Veja abaixo. | | `503` | Repita com espera. Nada foi feito. | | `500`, `504`, timeout | Repita com espera crescente. Se a operação move dinheiro, siga as regras do `502`. | ### Depois de um `502` [#depois-de-um-502] `PROVIDER_UNAVAILABLE`, ou `PROVIDER_REFUSED` com `details.status` `408` ou `429`, quer dizer que o banco não deu resposta final e a operação pode ter acontecido. Para repetir sem duplicar: * **Saque, pagamento de Pix copia e cola e transferência:** repita com a mesma `Idempotency-Key`, ou consulte antes de pedir de novo. * **Cobrança:** repita com o mesmo `externalRef`. * **Estorno e devolução de depósito:** consulte antes de pedir de novo. Essas rotas não aceitam `Idempotency-Key`. Os demais `PROVIDER_REFUSED` são recusa do banco: não repita. Cada rota lista as próprias recusas na [referência da API](/docs/conta-digital/endpoints). As recusas de credencial valem para todas. ## Requisição e limite de requisições [#requisição-e-limite-de-requisições] | `code` | HTTP | Quando | | ------------------------------ | ---- | ------------------------------------------------------------------------- | | `AUTH_TOO_MANY_REQUESTS` | 429 | Passou do limite de requisições. Espere o `Retry-After`. | | `RATE_LIMIT_UNAVAILABLE` | 503 | O controle do limite de requisições está fora do ar. Nada foi feito. | | `REQUEST_INTEGER_OUT_OF_RANGE` | 400 | Um número da requisição está fora da faixa aceita. | | `REQUEST_NOT_ALLOWED` | 405 | A rota não aceita esse método HTTP. | | `REQUEST_NUL_BYTE` | 400 | A requisição tem um caractere nulo. | | `REQUEST_PAYLOAD_TOO_LARGE` | 413 | O corpo passou do tamanho aceito. | | `REQUEST_UNKNOWN_QUERY_PARAM` | 400 | A rota não conhece um dos parâmetros de busca. | | `SCHEMA_INVALID` | 400 | Um campo ou parâmetro falta ou tem valor inválido. `details` aponta qual. | | `SCHEMA_MALFORMED_BODY` | 400 | O corpo não é um JSON válido. | | `SYSTEM_INTERNAL_ERROR` | 500 | Erro interno da PayZu. | ## Credencial [#credencial] Valem para todas as rotas. Mais detalhes em [Recusas de credencial](/docs/conta-digital/authentication#recusas-de-credencial). | `code` | HTTP | Quando | | ------------------------------ | ---- | ------------------------------------------------------------------------- | | `JWT_INVALID_AUTH_FORMAT` | 401 | Faltou o header `Authorization`, ou o esquema não é `Bearer` nem `Basic`. | | `TOKEN_EXPIRED` | 401 | A credencial tinha data de validade, e ela passou. | | `TOKEN_HOLDER_BLOCKED` | 403 | O titular da conta está bloqueado. | | `TOKEN_INVALID` | 401 | Credencial errada, inexistente ou revogada, ou token vencido ou alterado. | | `TOKEN_INVALID_AUTH_FORMAT` | 401 | O `Basic` não decodifica para `client_id:client_secret`. | | `TOKEN_IP_NOT_ALLOWED` | 403 | A chamada veio de um IP fora da lista da credencial. | | `TOKEN_MISSING_SCOPE` | 403 | A credencial não tem o escopo da rota. `details.scope` diz qual falta. | | `TOKEN_UNSUPPORTED_GRANT_TYPE` | 400 | `grant_type` ausente ou diferente de `client_credentials`. | ## Conta e banco [#conta-e-banco] | `code` | HTTP | Quando | | ----------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------- | | `ACCOUNT_BLOCKED_BY_PROVIDER` | 422 | O banco bloqueou esta operação na conta, até o desbloqueio. Na transferência, pode ser a entrada na conta de destino. | | `ACCOUNT_HELD_BY_STAFF` | 422 | A conta está retida pelo suporte, até a liberação. Na transferência, pode ser a conta de destino. | | `ACCOUNT_NOT_OPERABLE` | 412 | A conta não está ativa e não pode movimentar dinheiro. | | `PROVIDER_CAPABILITY_NOT_SUPPORTED` | 422 | A conta não oferece esta operação. | | `PROVIDER_NOT_PROVISIONED` | 412 | A conta ainda não terminou de ser aberta. | | `PROVIDER_OPERATION_UNAVAILABLE` | 422 | A operação está indisponível para a conta no momento. | | `PROVIDER_REFUSED` | 502 | O banco recusou a operação. Veja [Depois de um `502`](#depois-de-um-502). | | `PROVIDER_UNAVAILABLE` | 502 | O banco não respondeu a tempo, e a operação pode ter acontecido. Veja [Depois de um `502`](#depois-de-um-502). | ## Cobrança e callback [#cobrança-e-callback] | `code` | HTTP | Quando | | -------------------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------- | | `CALLBACK_SECRET_ALREADY_ISSUED` | 409 | A conta já tem segredo de callback. Para trocar, use a rotação. | | `CALLBACK_SECRET_MISSING` | 412 | A operação traz `callbackUrl`, e a conta ainda não tem segredo de callback. | | `PAYMENT_ABOVE_MAXIMUM` | 422 | O valor passa do máximo de cobrança da conta (`payment` nos [limites](/docs/conta-digital/statement#limites)). | | `PAYMENT_AMOUNT_NOT_ABOVE_FEE` | 422 | O valor não é maior que a tarifa de recebimento. | | `PAYMENT_BELOW_MINIMUM` | 422 | O valor fica abaixo do mínimo de cobrança da conta. | | `PAYMENT_CREATION_IN_FLIGHT` | 412 | Uma cobrança com o mesmo `externalRef` ainda está sendo criada. Repita em alguns segundos. | | `PAYMENT_DISABLED` | 403 | A cobrança está desativada para a conta. | | `PAYMENT_EXTERNAL_REF_MISMATCH` | 409 | Já existe uma cobrança com esse `externalRef`, e algum dado é diferente. Os campos diferentes vêm em `details.fields`. | | `PAYMENT_INVALID_CURSOR` | 400 | O `cursor` da listagem não vale. Recomece da primeira página. | | `PAYMENT_NOT_FOUND` | 404 | A cobrança não existe ou é de outra conta. | ## Estorno e devolução [#estorno-e-devolução] | `code` | HTTP | Quando | | ----------------------------- | ---- | -------------------------------------------------------------------------------------- | | `REFUND_ABOVE_REMAINING` | 422 | O valor pedido passa do que resta a devolver da cobrança ou do depósito. | | `REFUND_ABOVE_TICKET_MAX` | 422 | O valor passa do máximo por operação da conta, que é o do saque. | | `REFUND_ALREADY_REFUNDED` | 422 | A cobrança ou o depósito já foi devolvido por inteiro. | | `REFUND_DISABLED` | 403 | O estorno está desativado para a conta. | | `REFUND_INFRACTION_OPEN` | 422 | Há uma contestação MED aberta sobre a cobrança ou o depósito. Espere o resultado dela. | | `REFUND_INSUFFICIENT_BALANCE` | 422 | O saldo disponível não cobre o estorno. | | `REFUND_IN_FLIGHT` | 422 | Já há um estorno sendo processado. Espere o resultado. | | `REFUND_NOT_PAID` | 422 | A cobrança não foi paga. | ## Saque e pagamento de Pix copia e cola [#saque-e-pagamento-de-pix-copia-e-cola] | `code` | HTTP | Quando | | ---------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------- | | `QR_AMOUNT_DISAGREES` | 422 | O valor impresso no Pix copia e cola é diferente do que o banco informa para ele. Confirme o valor com quem cobrou. | | `QR_AMOUNT_MISMATCH` | 422 | O Pix copia e cola fixa um valor, e o `amount` enviado é outro. | | `QR_AMOUNT_REQUIRED` | 422 | O Pix copia e cola não fixa valor, e faltou `amount`. | | `QR_CRC` | 400 | O Pix copia e cola está corrompido. Copie de novo. | | `QR_MALFORMED` | 400 | O Pix copia e cola não está num formato válido. | | `QR_NOT_PIX` | 400 | O texto enviado não é um Pix copia e cola. | | `WITHDRAW_ABOVE_TICKET_MAX` | 422 | O valor passa do máximo de saque da conta (`withdraw` nos [limites](/docs/conta-digital/statement#limites)). | | `WITHDRAW_BELOW_TICKET_MIN` | 422 | O valor fica abaixo do mínimo de saque da conta. | | `WITHDRAW_DAILY_LIMIT` | 422 | O pedido passaria do teto diário das saídas por Pix (`dailyWithdraw`). | | `WITHDRAW_DISABLED` | 403 | O saque está desativado para a conta. | | `WITHDRAW_IDEMPOTENCY_KEY_REUSED` | 409 | A `Idempotency-Key` já foi usada num pedido com outros dados. | | `WITHDRAW_INSUFFICIENT_BALANCE` | 422 | O saldo disponível não cobre o valor mais a tarifa. `details` traz `available` e `required`. | | `WITHDRAW_INSUFFICIENT_PROVIDER_BALANCE` | 422 | O banco não cobre o saque naquele momento, mesmo com `available` suficiente. | | `WITHDRAW_INVALID_IDEMPOTENCY_KEY` | 400 | A `Idempotency-Key` não tem de 1 a 255 caracteres visíveis. | | `WITHDRAW_INVALID_PIX_KEY` | 400 | CPF ou CNPJ com dígito errado, ou 11 dígitos que não são CPF nem celular. | | `WITHDRAW_NOT_FOUND` | 404 | O saque não existe ou é de outra conta. | | `WITHDRAW_PIX_KEY_REFUSED_BY_PROVIDER` | 422 | O banco recusou a chave de destino. | | `WITHDRAW_PIX_KEY_TYPE_MISMATCH` | 400 | `pixKeyType` não bate com a chave. `details.inferred` diz o tipo deduzido. | | `WITHDRAW_UNRECOGNIZED_PIX_KEY` | 422 | Não dá para deduzir o tipo da chave. | ## Consulta de destinatário [#consulta-de-destinatário] | `code` | HTTP | Quando | | ------------------------------------- | ---- | ------------------------------------------------------------------------------------------------- | | `PIX_DEST_NOT_AUTHORIZED_AT_PROVIDER` | 502 | O banco não libera a consulta de chaves para esta conta. Fale com o suporte: repetir não resolve. | | `PIX_DEST_PIX_KEY` | 404 | A chave não existe no DICT, o diretório de chaves do Pix. Confira a chave. | | `PIX_DEST_THROTTLED` | 503 | Passou do limite de consultas do banco. Espere um pouco e repita. | | `PIX_DEST_UNAVAILABLE` | 503 | A consulta não aconteceu. Repita em instantes. | ## Chaves Pix [#chaves-pix] | `code` | HTTP | Quando | | ---------------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------- | | `PIX_KEY_DEFAULT_CANNOT_BE_REMOVED` | 422 | É a chave padrão. Defina outra como padrão antes de apagar. | | `PIX_KEY_DEFAULT_ON_PROVIDER` | 422 | A chave é a padrão da conta, mesmo que a listagem ainda não mostrasse isso. Defina outra como padrão antes de apagar. | | `PIX_KEY_DOCUMENT_NOT_HOLDER` | 400 | A chave de CPF ou CNPJ não é o documento do titular da conta. | | `PIX_KEY_DUPLICATED` | 409 | A chave já está cadastrada nesta conta. | | `PIX_KEY_NOT_FOUND` | 404 | A chave não existe, já foi apagada ou é de outra conta. | | `PIX_KEY_ONLY_ACTIVE_CAN_BE_DEFAULT` | 422 | A chave não está `ACTIVE` e não pode ser a padrão. | | `PIX_KEY_PROVIDER_REFUSED` | 422 | O banco recusou a chave. O motivo vem em `details.reason`. | | `PIX_KEY_RANDOM_KEY_NOT_ALLOWED` | 400 | Pedido de chave `EVP` com `key`. A chave aleatória é gerada pelo banco. | | `PIX_KEY_REQUIRED` | 400 | Tipo diferente de `EVP` sem `key`. | | `PIX_KEY_TYPE_NOT_SUPPORTED_BY_PROVIDER` | 422 | Tipo de chave que a conta não cria: `CPF`, `EMAIL` ou `PHONE`. | ## Transferência entre contas [#transferência-entre-contas] | `code` | HTTP | Quando | | ----------------------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------- | | `TRANSFER_ABOVE_TICKET_MAX` | 422 | O valor passa do máximo de transferência da conta (`internalTransfer` nos [limites](/docs/conta-digital/statement#limites)). | | `TRANSFER_AMBIGUOUS_DESTINATION` | 422 | A chave está ativa em mais de uma conta. | | `TRANSFER_BELOW_TICKET_MIN` | 422 | O valor fica abaixo do mínimo de transferência da conta. | | `TRANSFER_DAILY_LIMIT` | 422 | O pedido passaria do teto diário de transferências (`dailyInternalTransfer`). | | `TRANSFER_DESTINATION` | 404 | Nenhuma conta PayZu tem essa chave ativa. | | `TRANSFER_DESTINATION_NOT_ACTIVE` | 422 | A conta de destino não está ativa. | | `TRANSFER_DIFFERENT_PROVIDER` | 422 | A conta de destino opera em outro banco. Use um saque. | | `TRANSFER_DISABLED` | 403 | A transferência entre contas está desativada para a conta. | | `TRANSFER_IDEMPOTENCY_KEY_REUSED` | 409 | A `Idempotency-Key` já foi usada com outro valor ou destino. | | `TRANSFER_INSUFFICIENT_BALANCE` | 422 | O saldo disponível não cobre o valor mais a tarifa. `details` traz `available` e `required`. | | `TRANSFER_INVALID_IDEMPOTENCY_KEY` | 400 | A `Idempotency-Key` não tem de 1 a 255 caracteres visíveis. | | `TRANSFER_MAIN_ACCOUNT_DESTINATION` | 422 | A chave é da conta principal da PayZu, que não recebe transferência. Para pagar a PayZu, use uma cobrança. | | `TRANSFER_NOT_FOUND` | 404 | A transferência não existe ou é de outra conta. | | `TRANSFER_NOT_SUPPORTED` | 422 | A sua conta não faz transferência entre contas. | | `TRANSFER_NO_ORIGIN_KEY` | 422 | A sua conta não tem chave Pix ativa para enviar a transferência. | | `TRANSFER_SAME_ACCOUNT` | 422 | A chave é da sua própria conta. | ## Depósito e comprovante [#depósito-e-comprovante] | `code` | HTTP | Quando | | ---------------------------- | ---- | --------------------------------------------------------------------------------------------------- | | `DEPOSIT_NOT_FOUND` | 404 | O depósito não existe ou é de outra conta. | | `RECEIPT_MISSING_END_TO_END` | 422 | A operação ainda não tem end-to-end, e sem ele não há comprovante. Tente de novo em alguns minutos. | | `RECEIPT_NOT_SETTLED` | 422 | A operação ainda não foi concluída. O comprovante só sai depois. | ## Contestação [#contestação] | `code` | HTTP | Quando | | ---------------------- | ---- | --------------------------------------------- | | `INFRACTION_NOT_FOUND` | 404 | A contestação não existe ou é de outra conta. | ## Webhooks [#webhooks] | `code` | HTTP | Quando | | ------------------------ | ---- | --------------------------------------------------------------------------------------------------- | | `WEBHOOK_DUPLICATED_URL` | 409 | Outro endpoint da conta já usa essa URL. | | `WEBHOOK_HAS_DELIVERIES` | 409 | O endpoint já teve entrega e não pode ser excluído. Para parar de receber, mande `isActive: false`. | | `WEBHOOK_NOT_FOUND` | 404 | O endpoint não existe ou é de outra conta. |