PayZu Conta HubApoio
Erros
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"]
}
}| Campo | Tipo | Descrição |
|---|---|---|
message | string | Descrição em português, pronta para exibir. Pode mudar sem aviso. |
code | string | Código estável do erro. |
details | object | Contexto 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.
| HTTP | Significado | Exemplos |
|---|---|---|
400 | Requisição inválida: campo, formato ou parâmetro desconhecido. | SCHEMA_INVALID, REQUEST_UNKNOWN_QUERY_PARAM, WITHDRAW_INVALID_IDEMPOTENCY_KEY |
401 | Credencial ou token ausente, inválido ou vencido. | TOKEN_INVALID |
403 | Acesso recusado: IP fora da lista da credencial ou operação desabilitada na conta. | TOKEN_IP_NOT_ALLOWED, TOKEN_MISSING_SCOPE, WITHDRAW_DISABLED |
404 | Não encontrado, ou de outra conta. | PAYMENT_NOT_FOUND, WEBHOOK_NOT_FOUND |
409 | Conflito 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 |
412 | Falta um passo antes desta operação. | CALLBACK_SECRET_MISSING, PROVIDER_NOT_PROVISIONED, ACCOUNT_NOT_OPERABLE |
422 | Recusa de regra de negócio. | WITHDRAW_INSUFFICIENT_BALANCE, REFUND_ABOVE_REMAINING, QR_AMOUNT_REQUIRED |
429 | Cota de requisições excedida. Vem com o cabeçalho Retry-After. | AUTH_TOO_MANY_REQUESTS |
502 | O banco parceiro não respondeu ou recusou. | PROVIDER_UNAVAILABLE, PROVIDER_REFUSED |
503 | Consulta 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ódigo | HTTP | Mensagem |
|---|---|---|
REQUEST_UNKNOWN_QUERY_PARAM | 400 | A requisição tem um parâmetro de busca que esta rota não conhece. |
SCHEMA_INVALID | 400 | A requisição contém valores inválidos. |
TOKEN_INVALID | 401 | Credencial de integração inválida. |
TOKEN_IP_NOT_ALLOWED | 403 | Esta credencial não pode ser usada a partir deste IP. |
TOKEN_MISSING_SCOPE | 403 | Esta credencial não tem permissão para esta operação. |
PAYMENT_EXTERNAL_REF_MISMATCH | 409 | Já existe uma cobrança com esta referência, e os dados enviados não conferem com os dela. |
WITHDRAW_IDEMPOTENCY_KEY_REUSED | 409 | Este Idempotency-Key já foi usado por um saque com outros dados. |
CALLBACK_SECRET_MISSING | 412 | Gere o segredo de callback da conta antes de informar uma callbackUrl. |
PROVIDER_NOT_PROVISIONED | 412 | Esta conta ainda não terminou de ser aberta. |
REFUND_ABOVE_REMAINING | 422 | O valor do estorno é maior do que o que resta a devolver deste pagamento. |
REFUND_INFRACTION_OPEN | 422 | Esta cobrança tem uma contestação MED em andamento; o estorno fica indisponível até o desfecho. |
WITHDRAW_DAILY_LIMIT | 422 | O limite diário de saque desta conta foi atingido. |
WITHDRAW_INSUFFICIENT_BALANCE | 422 | Saldo insuficiente para este saque. |
AUTH_TOO_MANY_REQUESTS | 429 | Muitas tentativas. Tente novamente em alguns minutos. |
PROVIDER_UNAVAILABLE | 502 | Nã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ção | Cota |
|---|---|
| Troca de token | Limitada por client_id e por IP. |
| Criar cobrança | 60 por minuto por credencial e 120 por conta. |
| Saque | 5 por minuto por credencial e 10 por conta, somados com pagamento de copia e cola e devolução. |
| Transferência entre contas | 5 por minuto por credencial e 10 por conta. |
| Consulta de recebedor | 30 por minuto por conta e 300 por minuto somando todas as contas. |
| Reenvio de entrega de webhook | 20 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'json
{ "status": "ok", "updated_at": "2026-10-05T12:00:00.000Z" }Referência: Consultar o status do serviço