Limites de requisição
Nesta página
Limites por produtoLeia o tempo de esperaComo tratarQuando o limitador falhaErros de limiteEvite bloqueios por excesso de chamadas conhecendo os limites de cada produto e o tempo que a API manda esperar antes de repetir.
Limites por produto
O número não é publicado: a mensagem do erro informa a espera. O limite vale nestas operações:
- Leitura e pagamento de QR Code
- Devolução
- Consulta de chave, em
GET /pix/key - Transferência interna
| Operação | Por credencial | Por conta |
|---|---|---|
| Cobrança | 60 por minuto | 120 por minuto |
| Saque, somado com pagamento de copia e cola e devolução | 5 por minuto | 10 por minuto |
| Transferência interna | 5 por minuto | 10 por minuto |
| Consulta de recebedor | - | 30 por minuto |
A troca de token é limitada por client_id e por IP, sem número publicado. Os limites valem nas rotas da tabela e na devolução de depósito.
| Rotas | Limite por IP |
|---|---|
POST /v1/card-tokens | 10 por minuto |
| Criar assinatura pelo checkout | 10 por minuto |
| Pagar fatura e comprar pelo link, as duas rotas do checkout somadas | 10 por minuto |
| As quatro consultas do checkout, somadas | 60 por minuto |
Detalhes em Limites de requisição do PayZu Gateway.
As APIs de cartão (PayZu Payments e recorrência no cartão) não publicam limite.
Leia o tempo de espera
| Produto | Onde está a espera | Exemplo |
|---|---|---|
| PayZu Pix | Campo retryAfterSeconds do corpo | "retryAfterSeconds": 30 |
| PayZu Conta Hub | Header Retry-After e details.retryAfterSeconds | "details": { "retryAfterSeconds": 12 } |
| PayZu Gateway | Só na mensagem | "Muitas tentativas. Aguarde um minuto." |
{
"status": "ERROR",
"error": "Too Many Requests",
"errorCode": "PZG429",
"message": "Limite de consultas atingido. Tente novamente em breve. Tente novamente em 30s.",
"statusCode": 429,
"requestId": "cmbz0f8qk0001js04hp3e2n0f",
"retryAfterSeconds": 30
}{
"message": "Muitas tentativas. Tente novamente em alguns minutos.",
"code": "AUTH_TOO_MANY_REQUESTS",
"details": { "retryAfterSeconds": 12 }
}No PayZu Gateway, o 429 vem sem code, com error: too_many_requests e o request_id da chamada.
Como tratar
- Espere o tempo informado, com uma margem, antes de repetir.
- Repita criações só com a mesma chave. Leituras podem ser repetidas sem chave. Veja Idempotência.
- Reutilize o token. No PayZu Conta Hub, peça um token por processo e use-o pelos 15 minutos de validade.
- Consulte menos. No PayZu Pix, prefira os callbacks à consulta em laço. No PayZu Conta Hub, consulte o recebedor uma vez por destinatário, não a cada tentativa.
- Mais credenciais não aumentam o teto. As cotas por conta do PayZu Conta Hub somam todas as credenciais da conta.
No PayZu Conta Hub, uma rajada de devoluções bloqueia os saques do mesmo minuto.
As duas operações somam no mesmo limite.
Quando o limitador falha
No PayZu Conta Hub, as rotas com cota podem responder 503 quando a proteção de limite está indisponível. Espere alguns instantes e repita, com a mesma chave de idempotência nas operações que a aceitam.
Erros de limite
| Código | HTTP | Mensagem |
|---|---|---|
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. |
| Código | HTTP | Mensagem |
|---|---|---|
AUTH_TOO_MANY_REQUESTS | 429 | Muitas tentativas. Tente novamente em alguns minutos. |
RATE_LIMIT_UNAVAILABLE | 503 | Proteção de limite indisponível. Tente novamente em instantes. |
| Código | HTTP | Mensagem |
|---|---|---|
| - | 429 | Muitas tentativas. Aguarde um minuto. |
A lista inteira está no Catálogo de erros.