> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eyowallet.ru/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limiting

> Entenda como funciona o rate limiting na API Eyo Wallet

## Visão Geral

A API Eyo 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 Autenticadas (com API Key)

Rotas que requerem autenticação via API Key têm os seguintes limites:

| Métrica       | Valor                       |
| ------------- | --------------------------- |
| Limite        | 25 requisições por segundo  |
| Equivalente   | 1500 requisições por minuto |
| Janela        | 1 minuto                    |
| Identificador | API Key                     |

<Note>
  O rate limit é aplicado por API Key, permitindo que você tenha múltiplas API Keys para aumentar sua capacidade total.
</Note>

## Headers de Rate Limit

Todas as respostas incluem headers informativos sobre o rate limit:

```
X-RateLimit-Limit: 1500
X-RateLimit-Remaining: 1497
X-RateLimit-Reset: 1698765432
```

### Descrição dos Headers

<ResponseField name="X-RateLimit-Limit" type="integer">
  O número máximo de requisições permitidas na janela de tempo atual.
</ResponseField>

<ResponseField name="X-RateLimit-Remaining" type="integer">
  O número de requisições restantes na janela de tempo atual.
</ResponseField>

<ResponseField name="X-RateLimit-Reset" type="timestamp">
  Timestamp Unix (segundos) indicando quando a janela de rate limit será resetada.
</ResponseField>

## Resposta 429 (Too Many Requests)

Quando o rate limit é excedido, você receberá uma resposta HTTP 429:

<ResponseExample>
  ```json 429 Too Many Requests theme={null}
  {
    "success": false,
    "error": "Too Many Requests",
    "message": "Rate limit exceeded. Please try again in 5 seconds",
    "retryAfter": 5
  }
  ```
</ResponseExample>

### Campos da Resposta

<ResponseField name="error" type="string" required>
  Tipo do erro: "Too Many Requests"
</ResponseField>

<ResponseField name="message" type="string" required>
  Mensagem descritiva indicando quanto tempo esperar antes de tentar novamente.
</ResponseField>

<ResponseField name="retryAfter" type="integer" required>
  Número de segundos para aguardar antes de fazer uma nova requisição.
</ResponseField>

## Estratégias para Lidar com Rate Limiting

### 1. Implementar Backoff Exponencial

Quando receber um erro 429, implemente backoff exponencial antes de tentar novamente:

<CodeGroup>
  ```javascript Node.js theme={null}
  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));
      }
    }
  }
  ```

  ```python Python theme={null}
  import time
  import requests

  def make_request_with_retry(url, headers, max_retries=3):
      for attempt in range(max_retries):
          try:
              response = requests.get(url, headers=headers)
              
              if response.status_code == 429:
                  data = response.json()
                  wait_time = data.get('retryAfter', 2 ** attempt)
                  print(f"Rate limited. Waiting {wait_time} seconds...")
                  time.sleep(wait_time)
                  continue
              
              return response
          except Exception as e:
              if attempt == max_retries - 1:
                  raise
              time.sleep(2 ** attempt)
  ```
</CodeGroup>

### 2. Monitorar Headers de Rate Limit

Monitore os headers `X-RateLimit-Remaining` para evitar atingir o limite:

<CodeGroup>
  ```javascript Node.js theme={null}
  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;
  }
  ```

  ```python Python theme={null}
  import time
  import requests

  def make_request(url, api_key):
      response = requests.get(url, headers={'X-API-Key': api_key})
      
      remaining = int(response.headers.get('X-RateLimit-Remaining', 0))
      reset_time = int(response.headers.get('X-RateLimit-Reset', 0))
      
      if remaining < 2:
          wait_time = reset_time - int(time.time())
          print(f"Rate limit quase esgotado. Aguardando {wait_time} segundos...")
          time.sleep(wait_time)
      
      return response
  ```
</CodeGroup>

### 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 segundos
* `GET /api/v1/withdraw/list` - Cache de 60 segundos
* `GET /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:**

```bash theme={null}
# 10 requisições individuais
GET /api/v1/payment/get/payment_1
GET /api/v1/payment/get/payment_2
# ... mais 8 requisições
```

**Eficiente:**

```bash theme={null}
# 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:

<CodeGroup>
  ```javascript Node.js theme={null}
  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 }
    });
  }
  ```

  ```python Python theme={null}
  import random

  api_keys = [
      'vw_live_key1...',
      'vw_live_key2...',
      'vw_live_key3...'
  ]

  def get_random_api_key():
      return random.choice(api_keys)

  def make_request(url):
      api_key = get_random_api_key()
      return requests.get(url, headers={'X-API-Key': api_key})
  ```
</CodeGroup>

<Warning>
  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.
</Warning>

## Exemplos de Rate Limiting

### Exemplo: Rate Limit em Rotas Autenticadas

```bash theme={null}
# Primeiras 25 requisições em 1 segundo - OK
for i in {1..25}; do
  curl -H "X-API-Key: sua_key" https://api.eyowallet.ru/api/v1/user/balance
done

# Após 1500 requisições em 1 minuto - 429 Too Many Requests
curl -H "X-API-Key: sua_key" https://api.eyowallet.ru/api/v1/user/balance
# Resposta: {"error": "Too Many Requests", "retryAfter": 60}
```

## Boas Práticas

<Tip>
  **Sempre monitore os headers de rate limit**: Use `X-RateLimit-Remaining` para saber quantas requisições você ainda pode fazer.
</Tip>

<Tip>
  **Implemente retry com backoff**: Não faça requisições imediatamente após receber 429. Aguarde o tempo indicado em `retryAfter`.
</Tip>

<Tip>
  **Use cache quando possível**: Reduza o número de requisições usando dados em cache.
</Tip>

<Tip>
  **Agrupe operações**: Use endpoints de listagem em vez de múltiplas requisições individuais.
</Tip>

<Tip>
  **Teste em ambiente de desenvolvimento primeiro**: Entenda os limites antes de fazer deploy em produção.
</Tip>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Pagamentos" icon="credit-card" href="/api-reference/payments/create">
    Comece a criar e gerenciar transações PIX
  </Card>

  <Card title="Saques" icon="money-bill-transfer" href="/api-reference/withdraws/create">
    Aprenda a criar e gerenciar saques
  </Card>
</CardGroup>