PayZu PixApoio
Erros
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" }
]
}| Campo | Tipo | Descrição |
|---|---|---|
status | string | Sempre ERROR. |
error | string | Nome do status HTTP. |
errorCode | string | Código estável do erro, como PZV001. |
message | string | Motivo em texto, para exibir ou registrar. |
statusCode | integer | O mesmo status HTTP da resposta. |
requestId | string | Informe ao suporte para localizar a chamada. |
details | array | Erros de validação por campo, quando houver: field (caminho do campo) e message (motivo). |
retryAfterSeconds | integer | Segundos 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:PZG404tem 12 mensagens no catálogo, de "Transação não encontrada" a "Callback secret não encontrado". Amessagetambém carrega dados da conta ou da chamada, como o IP emPZA203e o valor mínimo da conta emPZD600. - Quando vier
retryAfterSeconds, espere esse tempo antes de repetir. O valor muda com a rota: 5 segundos nos424sem instituição disponível, 30 no limite de consultas de chave e de QR Code, 60 em devoluções e transferências. detailsvem nos400de validação.fieldfica vazio quando a regra envolve mais de um campo, como em GET /pix sem nenhum filtro.- Os
424vê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ódigo | HTTP | Mensagem |
|---|---|---|
PZV001 | 400 | Dados inválidos. Verifique os campos informados. QR Code inválido ou mal formatado |
PZA100 | 401 | Unauthorized |
PZA200 | 403 | Forbidden |
PZA203 | 403 | Acesso não permitido a partir do endereço de IP 203.0.113.10. |
PZA205 | 403 | Conta com token de saque exige IP cadastrado na whitelist. Cadastre o IP de origem (203.0.113.10) antes de operar. |
PZA206 | 403 | Conta aguardando assinatura do contrato. Assine o contrato enviado ao representante legal para liberar as operações. |
PZG404 | 404 | Transaçã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 |
PZC210 | 409 | Já existe uma operação com este identificador. Verifique o clientReference informado. |
PZC221 | 409 | Esta transação já foi reembolsada. |
PZC200 | 422 | Saldo insuficiente para esta operação. |
PZG422 | 422 | Nenhuma 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 |
PZS202 | 422 | Limite diário de saque excedido. |
PZD500 | 424 | Nenhuma instituição financeira disponível no momento. Tente novamente em instantes. |
PZI110 | 424 | Erro de comunicação com a instituição financeira. |
PZS500 | 424 | Nenhuma instituição financeira disponível para o saque no momento. Tente novamente em instantes. |
PZG429 | 429 | Limite 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.