PayZu PixApoio

Erros


Nesta páginaFormato do corpoDecida pelo códigoCódigos mais comuns

Formato do corpo

json
{
  "status": "ERROR",
  "error": "Bad Request",
  "errorCode": "PZV001",
  "message": "Dados inválidos. Verifique os campos informados.",
  "statusCode": 400,
  "requestId": "cmbz0f8qk0001js04hp3e2n0f",
  "details": [
    { "field": "url", "message": "Invalid URL" }
  ]
}
CampoTipoDescrição
statusstringSempre ERROR.
errorstringNome do status HTTP.
errorCodestringCódigo estável do erro, como PZV001.
messagestringMotivo em texto, para exibir ou registrar.
statusCodeintegerO mesmo status HTTP da resposta.
requestIdstringInforme ao suporte para localizar a chamada.
detailsarrayErros de validação por campo, quando houver: field (caminho do campo) e message (motivo).
retryAfterSecondsintegerSegundos de espera antes de repetir. Vem nos 429 e nos 424 sem instituição disponível (PZD500, PZS500).

Decida pelo código

  • Trate pelo errorCode. O mesmo código aparece com textos diferentes: PZG404 tem 12 mensagens no catálogo, de "Transação não encontrada" a "Callback secret não encontrado". A message também carrega dados da conta ou da chamada, como o IP em PZA203 e o valor mínimo da conta em PZD600.
  • Quando vier retryAfterSeconds, espere esse tempo antes de repetir. O valor muda com a rota: 5 segundos nos 424 sem instituição disponível, 30 no limite de consultas de chave e de QR Code, 60 em devoluções e transferências.
  • details vem nos 400 de validação. field fica vazio quando a regra envolve mais de um campo, como em GET /pix sem nenhum filtro.
  • Os 424 vêm da instituição financeira e podem ser repetidos depois de um intervalo. Já 500 PZI101 (operação não suportada para a instituição) não muda ao repetir.

Antes de repetir um POST que movimenta dinheiro, use o mesmo clientReference.

A PayZu retorna a operação já criada em vez de criar outra. Veja Idempotência e Boas práticas.

Códigos mais comuns

CódigoHTTPMensagem
PZV001400Dados inválidos. Verifique os campos informados.
QR Code inválido ou mal formatado
PZA100401Unauthorized
PZA200403Forbidden
PZA203403Acesso não permitido a partir do endereço de IP 203.0.113.10.
PZA205403Conta com token de saque exige IP cadastrado na whitelist. Cadastre o IP de origem (203.0.113.10) antes de operar.
PZA206403Conta aguardando assinatura do contrato. Assine o contrato enviado ao representante legal para liberar as operações.
PZG404404Transação não encontrada
Depósito pendente não encontrado
Extrato bancário não encontrado
Relatório não encontrado.
Webhook não encontrado
Log de webhook enviado não encontrado
Log de callback não encontrado
Nenhuma transação encontrada para os critérios fornecidos
Transação não encontrada ou não possui callback configurado
Callback secret não encontrado
Infração não encontrada
Defesa não encontrada para a infração
PZC210409Já existe uma operação com este identificador. Verifique o clientReference informado.
PZC221409Esta transação já foi reembolsada.
PZC200422Saldo insuficiente para esta operação.
PZG422422Nenhuma transação encontrada para o filtro aplicado.
Processamento de relatório ainda não concluido.
Limite de reenvios atingido. Tente novamente em 1 minuto.
Não é possível defender esta infração
PZS202422Limite diário de saque excedido.
PZD500424Nenhuma instituição financeira disponível no momento. Tente novamente em instantes.
PZI110424Erro de comunicação com a instituição financeira.
PZS500424Nenhuma instituição financeira disponível para o saque no momento. Tente novamente em instantes.
PZG429429Limite de requisições atingido. Tente novamente em breve.
Limite de consultas atingido. Tente novamente em breve. Tente novamente em 30s.
Limite de reembolsos atingido. Tente novamente em 1 minuto.

A checagem de IP (PZA203 e PZA205) vale em todas as rotas. Veja IP cadastrado.

Cada página de operação lista os códigos das suas rotas. A lista inteira, com todas as mensagens, está no Catálogo de erros.