Rate limits

Limite de requisições por chave, cabeçalhos RateLimit e como reagir ao 429.

Limite por chave

Cada chave pode fazer até 300 requisições por minuto, somando todas as rotas. A janela é fixa e reinicia a cada minuto. Chaves diferentes da mesma empresa têm limites separados.

Se a sua operação precisa de mais, fale com a MaxxiPay antes do pico.

Cabeçalhos

Cabeçalho	Valor
`RateLimit-Limit`	Requisições permitidas por janela.
`RateLimit-Remaining`	Requisições que ainda cabem na janela atual.
`RateLimit-Reset`	Segundos até a janela reiniciar.
`Retry-After`	Só no 429: segundos para tentar de novo.

CabeçalhosHTTP

HTTP/1.1 200 OK
RateLimit-Limit: 300
RateLimit-Remaining: 287
RateLimit-Reset: 41

Quando passar do limite

Passando do limite, a API responde 429 rate_limited sem executar nada. Espere os segundos de Retry-After e repita com a mesma Idempotency-Key.

Para não chegar lá, distribua tarefas em lote ao longo do minuto, use limit=100 nas listas e prefira webhooks a consultas repetidas.

RespostaJSON429 Too Many Requests

{
  "error": {
    "code": "rate_limited",
    "message": "Limite de 300 requisições por minuto atingido para esta chave. Tente de novo em 12s.",
    "requestId": "req_Vb3kQ9sLm2Xc8nTe"
  }
}