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

# Rate Limits

> Limites de requisições da Wapizap API

# Rate Limits

A Wapizap API implementa rate limiting para garantir estabilidade e disponibilidade do serviço para todos os usuários.

## Limites por Operação

| Operação         | Limite | Janela                 |
| ---------------- | ------ | ---------------------- |
| Enviar mensagens | 30     | por minuto / instância |
| Criar instâncias | 10     | por hora               |
| Listar recursos  | 60     | por minuto             |
| Operações gerais | 120    | por minuto             |
| Upload de mídia  | 20     | por minuto             |

***

## Limites por Plano

| Plano      | Requisições/min | Instâncias | Mensagens/dia |
| ---------- | --------------- | ---------- | ------------- |
| Free       | 60              | 1          | 1.000         |
| Starter    | 120             | 3          | 10.000        |
| Pro        | 300             | 10         | 100.000       |
| Enterprise | Personalizado   | Ilimitado  | Ilimitado     |

***

## Headers de Rate Limit

Toda resposta inclui headers informativos:

```http theme={null}
HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1705233060
```

| Header                  | Descrição                              |
| ----------------------- | -------------------------------------- |
| `X-RateLimit-Limit`     | Limite total de requisições no período |
| `X-RateLimit-Remaining` | Requisições restantes                  |
| `X-RateLimit-Reset`     | Timestamp Unix quando o limite reseta  |

***

## Resposta de Rate Limit Excedido

Quando você excede o limite, recebe HTTP 429:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after 60 seconds.",
    "details": {
      "retryAfter": 60,
      "limit": 30,
      "remaining": 0,
      "resetAt": "2026-01-15T10:35:00Z"
    }
  }
}
```

***

## Como Lidar com Rate Limits

### 1. Verificar Headers

```javascript theme={null}
async function makeRequest(url, options) {
  const response = await fetch(url, options);

  // Verificar headers
  const remaining = response.headers.get('X-RateLimit-Remaining');
  const resetAt = response.headers.get('X-RateLimit-Reset');

  if (remaining < 10) {
    console.warn(`Atenção: apenas ${remaining} requisições restantes`);
  }

  return response;
}
```

### 2. Implementar Exponential Backoff

```javascript theme={null}
async function requestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    const data = await response.json();
    const retryAfter = data.error?.details?.retryAfter || 60;

    console.log(`Rate limit. Aguardando ${retryAfter}s...`);
    await sleep(retryAfter * 1000);
  }

  throw new Error('Rate limit exceeded after max retries');
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
```

### 3. Implementar Queue de Mensagens

```javascript theme={null}
class MessageQueue {
  constructor(messagesPerMinute = 30) {
    this.queue = [];
    this.interval = (60 * 1000) / messagesPerMinute;
    this.processing = false;
  }

  add(message) {
    this.queue.push(message);
    this.process();
  }

  async process() {
    if (this.processing) return;
    this.processing = true;

    while (this.queue.length > 0) {
      const message = this.queue.shift();
      await this.sendMessage(message);
      await sleep(this.interval);
    }

    this.processing = false;
  }

  async sendMessage(message) {
    // Enviar via API
  }
}

// Uso
const queue = new MessageQueue(30); // 30 msgs/min
queue.add({ to: '5511999999999', text: 'Olá!' });
```

### 4. Distribuir entre Instâncias

Para alto volume, use múltiplas instâncias:

```javascript theme={null}
const instances = ['inst-1', 'inst-2', 'inst-3'];
let currentIndex = 0;

function getNextInstance() {
  const instance = instances[currentIndex];
  currentIndex = (currentIndex + 1) % instances.length;
  return instance;
}

async function sendMessage(to, text) {
  const instanceId = getNextInstance();
  return api.sendMessage({ instanceId, to, text });
}
```

***

## Boas Práticas

<CardGroup cols={2}>
  <Card title="Monitore os Headers" icon="chart-line">
    Acompanhe `X-RateLimit-Remaining` para evitar bloqueios.
  </Card>

  <Card title="Use Queues" icon="list">
    Implemente filas para controlar o fluxo de mensagens.
  </Card>

  <Card title="Cache Respostas" icon="database">
    Cache dados que não mudam frequentemente (listas, configurações).
  </Card>

  <Card title="Batch Requests" icon="layer-group">
    Agrupe operações quando possível.
  </Card>
</CardGroup>

***

## Limites do WhatsApp

Além dos limites da API, o WhatsApp tem suas próprias restrições:

<Warning>
  O WhatsApp pode bloquear contas que enviam muitas mensagens em curto período, especialmente para números que não responderam anteriormente.
</Warning>

**Recomendações:**

* Não envie mais de 200 mensagens/dia para números novos
* Aguarde respostas antes de enviar mais mensagens
* Evite mensagens idênticas em massa
* Varie o conteúdo das mensagens

***

## Solicitar Aumento de Limite

Se seu caso de uso requer limites maiores:

1. **Upgrade de plano** - Planos maiores têm limites mais altos
2. **Enterprise** - Limites personalizados para grandes volumes
3. **Contato** - [support@wapizap.com](mailto:support@wapizap.com)

Inclua na solicitação:

* Volume esperado (msgs/dia, msgs/min)
* Caso de uso
* Plano atual
* Instâncias necessárias

***

## FAQ

<AccordionGroup>
  <Accordion title="O rate limit é por API key ou por instância?">
    Depende da operação:

    * **Envio de mensagens**: Por instância
    * **Operações administrativas**: Por API key
  </Accordion>

  <Accordion title="O que acontece se eu exceder continuamente?">
    Exceder continuamente pode resultar em bloqueio temporário. Implemente backoff para evitar isso.
  </Accordion>

  <Accordion title="Posso ver meu histórico de uso?">
    Sim, no Dashboard em **Analytics → Uso da API**.
  </Accordion>
</AccordionGroup>