Saiba o que cada recusa da API quer dizer e quando vale repetir a chamada.
Toda recusa vem neste formato:
{ " message " : "Saldo insuficiente para este saque." , " code " : "WITHDRAW_INSUFFICIENT_BALANCE" , " details " : { " available " : 12500 , " required " : 20250 } } Campo Descrição messageTexto 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. codeCódigo estável, que não muda sem versão nova. É por ele que o seu sistema decide o que fazer. detailsContexto da recusa, quando existe. Pode não vir.
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.
Status O que fazer 400, 404, 409Não repita sem corrigir o pedido: a mesma chamada recebe a mesma recusa. 403, 422Nã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). 401Não repita em laço. Gere um token novo ou corrija a credencial. 412Repita só depois de cumprir o passo que falta, indicado pelo code. PAYMENT_CREATION_IN_FLIGHT se resolve em instantes. 429Repita depois do tempo em Retry-After. 502A operação pode ter acontecido. Veja abaixo. 503Repita com espera. Nada foi feito. 500, 504, timeoutRepita com espera crescente. Se a operação move dinheiro, siga as regras do 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 . As recusas de credencial valem para todas.
codeHTTP Quando AUTH_TOO_MANY_REQUESTS429 Passou do limite de requisições. Espere o Retry-After. RATE_LIMIT_UNAVAILABLE503 O controle do limite de requisições está fora do ar. Nada foi feito. REQUEST_INTEGER_OUT_OF_RANGE400 Um número da requisição está fora da faixa aceita. REQUEST_NOT_ALLOWED405 A rota não aceita esse método HTTP. REQUEST_NUL_BYTE400 A requisição tem um caractere nulo. REQUEST_PAYLOAD_TOO_LARGE413 O corpo passou do tamanho aceito. REQUEST_UNKNOWN_QUERY_PARAM400 A rota não conhece um dos parâmetros de busca. SCHEMA_INVALID400 Um campo ou parâmetro falta ou tem valor inválido. details aponta qual. SCHEMA_MALFORMED_BODY400 O corpo não é um JSON válido. SYSTEM_INTERNAL_ERROR500 Erro interno da PayZu.
Valem para todas as rotas. Mais detalhes em Recusas de credencial .
codeHTTP Quando JWT_INVALID_AUTH_FORMAT401 Faltou o header Authorization, ou o esquema não é Bearer nem Basic. TOKEN_EXPIRED401 A credencial tinha data de validade, e ela passou. TOKEN_HOLDER_BLOCKED403 O titular da conta está bloqueado. TOKEN_INVALID401 Credencial errada, inexistente ou revogada, ou token vencido ou alterado. TOKEN_INVALID_AUTH_FORMAT401 O Basic não decodifica para client_id:client_secret. TOKEN_IP_NOT_ALLOWED403 A chamada veio de um IP fora da lista da credencial. TOKEN_MISSING_SCOPE403 A credencial não tem o escopo da rota. details.scope diz qual falta. TOKEN_UNSUPPORTED_GRANT_TYPE400 grant_type ausente ou diferente de client_credentials.
codeHTTP Quando ACCOUNT_BLOCKED_BY_PROVIDER422 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_STAFF422 A conta está retida pelo suporte, até a liberação. Na transferência, pode ser a conta de destino. ACCOUNT_NOT_OPERABLE412 A conta não está ativa e não pode movimentar dinheiro. PROVIDER_CAPABILITY_NOT_SUPPORTED422 A conta não oferece esta operação. PROVIDER_NOT_PROVISIONED412 A conta ainda não terminou de ser aberta. PROVIDER_OPERATION_UNAVAILABLE422 A operação está indisponível para a conta no momento. PROVIDER_REFUSED502 O banco recusou a operação. Veja Depois de um 502 . PROVIDER_UNAVAILABLE502 O banco não respondeu a tempo, e a operação pode ter acontecido. Veja Depois de um 502 .
codeHTTP Quando CALLBACK_SECRET_ALREADY_ISSUED409 A conta já tem segredo de callback. Para trocar, use a rotação. CALLBACK_SECRET_MISSING412 A operação traz callbackUrl, e a conta ainda não tem segredo de callback. PAYMENT_ABOVE_MAXIMUM422 O valor passa do máximo de cobrança da conta (payment nos limites ). PAYMENT_AMOUNT_NOT_ABOVE_FEE422 O valor não é maior que a tarifa de recebimento. PAYMENT_BELOW_MINIMUM422 O valor fica abaixo do mínimo de cobrança da conta. PAYMENT_CREATION_IN_FLIGHT412 Uma cobrança com o mesmo externalRef ainda está sendo criada. Repita em alguns segundos. PAYMENT_DISABLED403 A cobrança está desativada para a conta. PAYMENT_EXTERNAL_REF_MISMATCH409 Já existe uma cobrança com esse externalRef, e algum dado é diferente. Os campos diferentes vêm em details.fields. PAYMENT_INVALID_CURSOR400 O cursor da listagem não vale. Recomece da primeira página. PAYMENT_NOT_FOUND404 A cobrança não existe ou é de outra conta.
codeHTTP Quando REFUND_ABOVE_REMAINING422 O valor pedido passa do que resta a devolver da cobrança ou do depósito. REFUND_ABOVE_TICKET_MAX422 O valor passa do máximo por operação da conta, que é o do saque. REFUND_ALREADY_REFUNDED422 A cobrança ou o depósito já foi devolvido por inteiro. REFUND_DISABLED403 O estorno está desativado para a conta. REFUND_INFRACTION_OPEN422 Há uma contestação MED aberta sobre a cobrança ou o depósito. Espere o resultado dela. REFUND_INSUFFICIENT_BALANCE422 O saldo disponível não cobre o estorno. REFUND_IN_FLIGHT422 Já há um estorno sendo processado. Espere o resultado. REFUND_NOT_PAID422 A cobrança não foi paga.
codeHTTP Quando QR_AMOUNT_DISAGREES422 O valor impresso no Pix copia e cola é diferente do que o banco informa para ele. Confirme o valor com quem cobrou. QR_AMOUNT_MISMATCH422 O Pix copia e cola fixa um valor, e o amount enviado é outro. QR_AMOUNT_REQUIRED422 O Pix copia e cola não fixa valor, e faltou amount. QR_CRC400 O Pix copia e cola está corrompido. Copie de novo. QR_MALFORMED400 O Pix copia e cola não está num formato válido. QR_NOT_PIX400 O texto enviado não é um Pix copia e cola. WITHDRAW_ABOVE_TICKET_MAX422 O valor passa do máximo de saque da conta (withdraw nos limites ). WITHDRAW_BELOW_TICKET_MIN422 O valor fica abaixo do mínimo de saque da conta. WITHDRAW_DAILY_LIMIT422 O pedido passaria do teto diário das saídas por Pix (dailyWithdraw). WITHDRAW_DISABLED403 O saque está desativado para a conta. WITHDRAW_IDEMPOTENCY_KEY_REUSED409 A Idempotency-Key já foi usada num pedido com outros dados. WITHDRAW_INSUFFICIENT_BALANCE422 O saldo disponível não cobre o valor mais a tarifa. details traz available e required. WITHDRAW_INSUFFICIENT_PROVIDER_BALANCE422 O banco não cobre o saque naquele momento, mesmo com available suficiente. WITHDRAW_INVALID_IDEMPOTENCY_KEY400 A Idempotency-Key não tem de 1 a 255 caracteres visíveis. WITHDRAW_INVALID_PIX_KEY400 CPF ou CNPJ com dígito errado, ou 11 dígitos que não são CPF nem celular. WITHDRAW_NOT_FOUND404 O saque não existe ou é de outra conta. WITHDRAW_PIX_KEY_REFUSED_BY_PROVIDER422 O banco recusou a chave de destino. WITHDRAW_PIX_KEY_TYPE_MISMATCH400 pixKeyType não bate com a chave. details.inferred diz o tipo deduzido.WITHDRAW_UNRECOGNIZED_PIX_KEY422 Não dá para deduzir o tipo da chave.
codeHTTP Quando PIX_DEST_NOT_AUTHORIZED_AT_PROVIDER502 O banco não libera a consulta de chaves para esta conta. Fale com o suporte: repetir não resolve. PIX_DEST_PIX_KEY404 A chave não existe no DICT, o diretório de chaves do Pix. Confira a chave. PIX_DEST_THROTTLED503 Passou do limite de consultas do banco. Espere um pouco e repita. PIX_DEST_UNAVAILABLE503 A consulta não aconteceu. Repita em instantes.
codeHTTP Quando PIX_KEY_DEFAULT_CANNOT_BE_REMOVED422 É a chave padrão. Defina outra como padrão antes de apagar. PIX_KEY_DEFAULT_ON_PROVIDER422 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_HOLDER400 A chave de CPF ou CNPJ não é o documento do titular da conta. PIX_KEY_DUPLICATED409 A chave já está cadastrada nesta conta. PIX_KEY_NOT_FOUND404 A chave não existe, já foi apagada ou é de outra conta. PIX_KEY_ONLY_ACTIVE_CAN_BE_DEFAULT422 A chave não está ACTIVE e não pode ser a padrão. PIX_KEY_PROVIDER_REFUSED422 O banco recusou a chave. O motivo vem em details.reason. PIX_KEY_RANDOM_KEY_NOT_ALLOWED400 Pedido de chave EVP com key. A chave aleatória é gerada pelo banco. PIX_KEY_REQUIRED400 Tipo diferente de EVP sem key. PIX_KEY_TYPE_NOT_SUPPORTED_BY_PROVIDER422 Tipo de chave que a conta não cria: CPF, EMAIL ou PHONE.
codeHTTP Quando TRANSFER_ABOVE_TICKET_MAX422 O valor passa do máximo de transferência da conta (internalTransfer nos limites ). TRANSFER_AMBIGUOUS_DESTINATION422 A chave está ativa em mais de uma conta. TRANSFER_BELOW_TICKET_MIN422 O valor fica abaixo do mínimo de transferência da conta. TRANSFER_DAILY_LIMIT422 O pedido passaria do teto diário de transferências (dailyInternalTransfer). TRANSFER_DESTINATION404 Nenhuma conta PayZu tem essa chave ativa. TRANSFER_DESTINATION_NOT_ACTIVE422 A conta de destino não está ativa. TRANSFER_DIFFERENT_PROVIDER422 A conta de destino opera em outro banco. Use um saque. TRANSFER_DISABLED403 A transferência entre contas está desativada para a conta. TRANSFER_IDEMPOTENCY_KEY_REUSED409 A Idempotency-Key já foi usada com outro valor ou destino. TRANSFER_INSUFFICIENT_BALANCE422 O saldo disponível não cobre o valor mais a tarifa. details traz available e required. TRANSFER_INVALID_IDEMPOTENCY_KEY400 A Idempotency-Key não tem de 1 a 255 caracteres visíveis. TRANSFER_MAIN_ACCOUNT_DESTINATION422 A chave é da conta principal da PayZu, que não recebe transferência. Para pagar a PayZu, use uma cobrança. TRANSFER_NOT_FOUND404 A transferência não existe ou é de outra conta. TRANSFER_NOT_SUPPORTED422 A sua conta não faz transferência entre contas. TRANSFER_NO_ORIGIN_KEY422 A sua conta não tem chave Pix ativa para enviar a transferência. TRANSFER_SAME_ACCOUNT422 A chave é da sua própria conta.
codeHTTP Quando DEPOSIT_NOT_FOUND404 O depósito não existe ou é de outra conta. RECEIPT_MISSING_END_TO_END422 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_SETTLED422 A operação ainda não foi concluída. O comprovante só sai depois.
codeHTTP Quando INFRACTION_NOT_FOUND404 A contestação não existe ou é de outra conta.
codeHTTP Quando WEBHOOK_DUPLICATED_URL409 Outro endpoint da conta já usa essa URL. WEBHOOK_HAS_DELIVERIES409 O endpoint já teve entrega e não pode ser excluído. Para parar de receber, mande isActive: false. WEBHOOK_NOT_FOUND404 O endpoint não existe ou é de outra conta.
