PayZu Conta HubApoio

Erros


Nesta páginaFormatoDecida pelo códigoCódigos mais comunsCotasStatus do serviço

Todas as respostas de erro do PayZu Conta Hub têm o mesmo corpo JSON.

Formato

json
{
  "message": "A requisição tem um parâmetro de busca que esta rota não conhece.",
  "code": "REQUEST_UNKNOWN_QUERY_PARAM",
  "details": {
    "unknownParams": ["page"],
    "accepted": ["amount", "cursor", "dateFrom", "dateTo", "document", "endToEndId", "limit", "name", "sortBy", "sortDirection", "status"]
  }
}
CampoTipoDescrição
messagestringDescrição em português, pronta para exibir. Pode mudar sem aviso.
codestringCódigo estável do erro.
detailsobjectContexto estruturado, quando existe: parâmetros aceitos, retryAfterSeconds, reason do banco parceiro.

Decida pelo código

Compare code com os valores do Catálogo de erros, nunca o texto de message. Para um código que o seu sistema ainda não conhece, o status HTTP indica a família do problema.

HTTPSignificadoExemplos
400Requisição inválida: campo, formato ou parâmetro desconhecido.SCHEMA_INVALID, REQUEST_UNKNOWN_QUERY_PARAM, WITHDRAW_INVALID_IDEMPOTENCY_KEY
401Credencial ou token ausente, inválido ou vencido.TOKEN_INVALID
403Acesso recusado: IP fora da lista da credencial ou operação desabilitada na conta.TOKEN_IP_NOT_ALLOWED, TOKEN_MISSING_SCOPE, WITHDRAW_DISABLED
404Não encontrado, ou de outra conta.PAYMENT_NOT_FOUND, WEBHOOK_NOT_FOUND
409Conflito com o estado atual (repetição com outros dados, recurso que já existe ou que não pode ser removido).WITHDRAW_IDEMPOTENCY_KEY_REUSED, PAYMENT_EXTERNAL_REF_MISMATCH, WEBHOOK_DUPLICATED_URL, WEBHOOK_HAS_DELIVERIES
412Falta um passo antes desta operação.CALLBACK_SECRET_MISSING, PROVIDER_NOT_PROVISIONED, ACCOUNT_NOT_OPERABLE
422Recusa de regra de negócio.WITHDRAW_INSUFFICIENT_BALANCE, REFUND_ABOVE_REMAINING, QR_AMOUNT_REQUIRED
429Cota de requisições excedida. Vem com o cabeçalho Retry-After.AUTH_TOO_MANY_REQUESTS
502O banco parceiro não respondeu ou recusou.PROVIDER_UNAVAILABLE, PROVIDER_REFUSED
503Consulta ou limitador indisponível; nada foi feito, pode repetir.PIX_DEST_UNAVAILABLE, RATE_LIMIT_UNAVAILABLE

Repetir um 403 não resolve.

Chame de um IP da lista da credencial ou fale com o suporte da PayZu.

Códigos mais comuns

CódigoHTTPMensagem
REQUEST_UNKNOWN_QUERY_PARAM400A requisição tem um parâmetro de busca que esta rota não conhece.
SCHEMA_INVALID400A requisição contém valores inválidos.
TOKEN_INVALID401Credencial de integração inválida.
TOKEN_IP_NOT_ALLOWED403Esta credencial não pode ser usada a partir deste IP.
TOKEN_MISSING_SCOPE403Esta credencial não tem permissão para esta operação.
PAYMENT_EXTERNAL_REF_MISMATCH409Já existe uma cobrança com esta referência, e os dados enviados não conferem com os dela.
WITHDRAW_IDEMPOTENCY_KEY_REUSED409Este Idempotency-Key já foi usado por um saque com outros dados.
CALLBACK_SECRET_MISSING412Gere o segredo de callback da conta antes de informar uma callbackUrl.
PROVIDER_NOT_PROVISIONED412Esta conta ainda não terminou de ser aberta.
REFUND_ABOVE_REMAINING422O valor do estorno é maior do que o que resta a devolver deste pagamento.
REFUND_INFRACTION_OPEN422Esta cobrança tem uma contestação MED em andamento; o estorno fica indisponível até o desfecho.
WITHDRAW_DAILY_LIMIT422O limite diário de saque desta conta foi atingido.
WITHDRAW_INSUFFICIENT_BALANCE422Saldo insuficiente para este saque.
AUTH_TOO_MANY_REQUESTS429Muitas tentativas. Tente novamente em alguns minutos.
PROVIDER_UNAVAILABLE502Não houve resposta a tempo. Tente de novo em instantes.

Todos os códigos do PayZu Conta Hub estão no Catálogo de erros.

Cotas

OperaçãoCota
Troca de tokenLimitada por client_id e por IP.
Criar cobrança60 por minuto por credencial e 120 por conta.
Saque5 por minuto por credencial e 10 por conta, somados com pagamento de copia e cola e devolução.
Transferência entre contas5 por minuto por credencial e 10 por conta.
Consulta de recebedor30 por minuto por conta e 300 por minuto somando todas as contas.
Reenvio de entrega de webhook20 por minuto por conta.

Status do serviço

GET /status não exige credencial e responde status: ok com o instante da resposta. Quando o serviço não está saudável, responde 500. Use na sua verificação de disponibilidade; a rota não substitui o tratamento de 502 e 503 nas operações.

bash
curl --request GET \
  --url 'https://api.sandbox.payzu.dev/api/v1/status'

Referência: Consultar o status do serviço