Comece aquiSegurança da API

Limites de requisição


Nesta páginaLimites por produtoLeia o tempo de esperaComo tratarQuando o limitador falhaErros de limite

Evite 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

As APIs de cartão (PayZu Payments e recorrência no cartão) não publicam limite.

Leia o tempo de espera

ProdutoOnde está a esperaExemplo
PayZu PixCampo retryAfterSeconds do corpo"retryAfterSeconds": 30
PayZu Conta HubHeader Retry-After e details.retryAfterSeconds"details": { "retryAfterSeconds": 12 }
PayZu GatewaySó na mensagem"Muitas tentativas. Aguarde um minuto."
json
{
  "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
}

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ódigoHTTPMensagem
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 lista inteira está no Catálogo de erros.