Limites de taxa
Para garantir o desempenho e a confiabilidade da API PayerScan para todos os comerciantes, aplicamos limites de taxa da API com uma estrutura de controle duplo (Burst e Sustained).
Escopo dos limites
Os limites de taxa são aplicados por API Key. Se a API Key não for fornecida, o limite é aplicado por endereço IP. Isso significa:
- Vários servidores usando a mesma API Key compartilham o mesmo limite.
- Lojas diferentes com API Keys diferentes têm limites independentes.
API de criação de fatura (POST /payment/crypto)
| Tipo de limite | Limiar |
|---|---|
| Burst (máximo instantâneo) | 5 requisições / segundo |
| Sustained | 60 requisições / minuto |
API de consulta de fatura (GET /invoice/:trans_id)
| Tipo de limite | Limiar |
|---|---|
| Burst (máximo instantâneo) | 20 requisições / segundo |
| Sustained | 200 requisições / minuto |
Quando os limites são excedidos
Se o seu sistema exceder o limiar configurado, a API retornará:
- Código de status HTTP:
429 Too Many Requests
Limite burst excedido (POST /payment/crypto):
{
"status": "error",
"message": "Too many requests per second. Please slow down.",
"error_code": "RATE_LIMIT_EXCEEDED",
"limit_type": "burst",
"retry_after_seconds": 1
}
Limite sustained excedido (POST /payment/crypto):
{
"status": "error",
"message": "Rate limit exceeded. Maximum 60 requests per minute.",
"error_code": "RATE_LIMIT_EXCEEDED",
"limit_type": "sustained",
"retry_after_seconds": 60
}
Os valores de message e retry_after_seconds variam conforme o endpoint. Por exemplo, o endpoint GET retorna "Maximum 200 requests per minute." com "retry_after_seconds": 60.
Headers de limite de taxa
A API retorna headers de limite de taxa padrão em cada resposta:
| Header | Descrição |
|---|---|
RateLimit-Limit | Número máximo de requisições permitidas na janela atual. |
RateLimit-Remaining | Número de requisições restantes na janela atual. |
RateLimit-Reset | Tempo (em segundos) até a janela de limite ser redefinida. |
Use estes headers para monitorar seu uso e evitar atingir os limites.
Configure um mecanismo de Exponential Backoff na sua biblioteca de requisições (ex.: Axios-retry) para tentar novamente automaticamente após o valor retry_after_seconds ao encontrar um erro HTTP 429.