Visão Geral
A API Vision Wallet implementa rate limiting para garantir estabilidade, segurança e uso justo dos recursos. Diferentes tipos de rotas têm limites diferentes baseados no método de autenticação.
Limites por Tipo de Rota
Rotas que requerem autenticação via API Key têm os seguintes limites:
| Métrica | Valor |
|---|
| Limite | 10 requisições por segundo |
| Equivalente | 600 requisições por minuto |
| Janela | 1 segundo |
| Identificador | API Key |
O rate limit é aplicado por API Key, permitindo que você tenha múltiplas API Keys para aumentar sua capacidade total.
Rotas Admin
Rotas administrativas têm limites ainda mais restritivos:
| Métrica | Valor |
|---|
| Limite | 30 requisições por minuto |
| Janela | 60 segundos |
| Identificador | API Key |
Rotas de Registro
A rota de registro de usuário tem um cooldown especial:
| Métrica | Valor |
|---|
| Cooldown | 30 segundos entre requisições |
| Identificador | API Key ou IP |
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1698765432
O número máximo de requisições permitidas na janela de tempo atual.
O número de requisições restantes na janela de tempo atual.
Timestamp Unix (segundos) indicando quando a janela de rate limit será resetada.
Resposta 429 (Too Many Requests)
Quando o rate limit é excedido, você receberá uma resposta HTTP 429:
{
"success": false,
"error": "Too Many Requests",
"message": "Rate limit exceeded. Please try again in 5 seconds",
"retryAfter": 5
}
Campos da Resposta
Tipo do erro: “Too Many Requests”
Mensagem descritiva indicando quanto tempo esperar antes de tentar novamente.
Número de segundos para aguardar antes de fazer uma nova requisição.
1. Implementar Backoff Exponencial
Quando receber um erro 429, implemente backoff exponencial antes de tentar novamente:
async function makeRequestWithRetry(url, options, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
const response = await fetch(url, options);
if (response.status === 429) {
const data = await response.json();
const waitTime = data.retryAfter || Math.pow(2, attempt);
console.log(`Rate limited. Waiting ${waitTime} seconds...`);
await new Promise(resolve => setTimeout(resolve, waitTime * 1000));
continue;
}
return response;
} catch (error) {
if (attempt === maxRetries - 1) throw error;
await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
}
}
}
X-RateLimit-Remaining para evitar atingir o limite:
async function makeRequest(url, apiKey) {
const response = await fetch(url, {
headers: {
'X-API-Key': apiKey
}
});
const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
if (remaining < 2) {
const waitTime = resetTime - Math.floor(Date.now() / 1000);
console.log(`Rate limit quase esgotado. Aguardando ${waitTime} segundos...`);
await new Promise(resolve => setTimeout(resolve, waitTime * 1000));
}
return response;
}
3. Usar Cache Quando Possível
Algumas rotas têm cache implementado. Use essas rotas para reduzir o número de requisições:
GET /api/v1/payment/list - Cache de 60 segundosGET /api/v1/withdraw/list - Cache de 60 segundosGET /api/v1/user/balance - Cache variável
4. Agrupar Operações
Em vez de fazer múltiplas requisições individuais, use endpoints de listagem quando possível:
Ineficiente:
# 10 requisições individuais
GET /api/v1/payment/get/payment_1
GET /api/v1/payment/get/payment_2
# ... mais 8 requisições
# 1 requisição para listar todos
GET /api/v1/payment/list?limit=10
5. Usar Múltiplas API Keys
Se você precisa de maior capacidade, crie múltiplas API Keys e distribua as requisições entre elas:
const apiKeys = [
'vw_live_key1...',
'vw_live_key2...',
'vw_live_key3...'
];
let currentKeyIndex = 0;
function getNextApiKey() {
const key = apiKeys[currentKeyIndex];
currentKeyIndex = (currentKeyIndex + 1) % apiKeys.length;
return key;
}
async function makeRequest(url) {
const apiKey = getNextApiKey();
return fetch(url, {
headers: { 'X-API-Key': apiKey }
});
}
Distribuir requisições entre múltiplas API Keys pode ajudar, mas certifique-se de que cada API Key tenha as permissões necessárias para as operações que você está realizando.
Exemplos de Rate Limiting
Exemplo: Rate Limit em Rotas Autenticadas
# Primeiras 10 requisições em 1 segundo - OK
for i in {1..10}; do
curl -H "X-API-Key: sua_key" https://api.visionwallet.com.br/api/v1/user/balance
done
# 11ª requisição - 429 Too Many Requests
curl -H "X-API-Key: sua_key" https://api.visionwallet.com.br/api/v1/user/balance
# Resposta: {"error": "Too Many Requests", "retryAfter": 1}
Boas Práticas
Sempre monitore os headers de rate limit: Use X-RateLimit-Remaining para saber quantas requisições você ainda pode fazer.
Implemente retry com backoff: Não faça requisições imediatamente após receber 429. Aguarde o tempo indicado em retryAfter.
Use cache quando possível: Reduza o número de requisições usando dados em cache.
Agrupe operações: Use endpoints de listagem em vez de múltiplas requisições individuais.
Teste em ambiente de desenvolvimento primeiro: Entenda os limites antes de fazer deploy em produção.
Próximos Passos
