Rate Limits

A Oxenty API implementa rate limiting para garantir estabilidade e justiça no uso dos recursos. Os limites variam de acordo com o plano contratado.

Limites por Plano

Free
Inicial
Intermediário
Empresarial

Recurso	Limite
Requisições/minuto	40
Sessões ativas	1
Mensagens/dia	480
Webhooks	1

Recurso	Limite
Requisições/minuto	120
Sessões ativas	1
Mensagens/dia	Ilimitadas
Webhooks	1

Recurso	Limite
Requisições/minuto	360
Sessões ativas	3
Mensagens/dia	Ilimitadas
Webhooks	3

Recurso	Limite
Requisições/minuto	Ilimitadas
Sessões ativas	10
Mensagens/dia	Ilimitadas
Webhooks	Ilimitadas

Headers de Rate Limit

Toda resposta da API inclui headers informativos sobre o estado atual dos limites:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1704067200

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

Resposta de Limite Excedido

Quando você excede o rate limit, a API retorna status 429 Too Many Requests:

{
  "statusCode": 429,
  "error": "TOO_MANY_REQUESTS",
  "message": "Rate limit exceeded. Try again in 45 seconds.",
  "retryAfter": 45
}

O header Retry-After também é incluído indicando em quantos segundos você pode tentar novamente.

Estratégias de Tratamento

Exponential Backoff

Implemente retries com backoff exponencial para lidar com rate limits:

async function requestWithRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  let lastError: Error;
  
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error: any) {
      if (error.status !== 429) throw error;
      
      lastError = error;
      const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
  
  throw lastError;
}

// Uso
const sessions = await requestWithRetry(() => 
  client.sessions.list()
);

import time
import requests

def request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        
        if response.status_code != 429:
            return response
        
        delay = (2 ** attempt)  # 1s, 2s, 4s
        time.sleep(delay)
    
    return response

# Uso
response = request_with_retry(
  'https://api.oxenty.api.br/api/sessions',
    headers={'X-API-Key': API_KEY}
)

Queue de Requisições

Para alto volume, implemente uma queue que respeite os limites:

class RequestQueue {
  private queue: Array<() => Promise<void>> = [];
  private processing = false;
  private requestsPerMinute: number;
  private interval: number;

  constructor(requestsPerMinute: number) {
    this.requestsPerMinute = requestsPerMinute;
    this.interval = 60000 / requestsPerMinute;
  }

  async add<T>(fn: () => Promise<T>): Promise<T> {
    return new Promise((resolve, reject) => {
      this.queue.push(async () => {
        try {
          const result = await fn();
          resolve(result);
        } catch (error) {
          reject(error);
        }
      });
      this.process();
    });
  }

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

    while (this.queue.length > 0) {
      const fn = this.queue.shift();
      if (fn) {
        await fn();
        await new Promise(r => setTimeout(r, this.interval));
      }
    }

    this.processing = false;
  }
}

// Uso
const queue = new RequestQueue(60); // 60 req/min

await queue.add(() => client.messages.send(sessionId, message1));
await queue.add(() => client.messages.send(sessionId, message2));

Rate Limits por Endpoint

Alguns endpoints possuem limites específicos mais restritivos:

Endpoint	Limite	Motivo
`POST /sessions`	5/minuto	Criação de sessão é custosa
`POST /messages/send`	Por plano	Evitar spam
`GET /contacts/check`	10/minuto	Rate limit do WhatsApp
`POST /groups`	3/minuto	Rate limit do WhatsApp

O WhatsApp possui seus próprios rate limits internos. Mesmo que a API permita, envios muito frequentes podem resultar em ban temporário do número.

Boas Práticas

Monitore os Headers

Sempre verifique X-RateLimit-Remaining antes de fazer múltiplas requisições.

Implemente Caching

Cache respostas de endpoints que mudam pouco (ex: lista de sessões).

Use Webhooks

Ao invés de polling, configure webhooks para receber eventos em tempo real.

Batch quando possível

Alguns endpoints suportam operações em lote. Prefira enviar múltiplos itens em uma requisição.

Upgrade de Plano

Se você está frequentemente atingindo os limites, considere fazer upgrade do seu plano:

Ver Planos

Compare os planos disponíveis

Vendas e planos Enterprise: +55 87 8114-8453

Introdução

Guias

Limites por Plano

Headers de Rate Limit

Resposta de Limite Excedido

Estratégias de Tratamento

Exponential Backoff

Queue de Requisições

Rate Limits por Endpoint

Boas Práticas

Upgrade de Plano

Ver Planos

WhatsApp

​Limites por Plano

​Headers de Rate Limit

​Resposta de Limite Excedido

​Estratégias de Tratamento

​Exponential Backoff

​Queue de Requisições

​Rate Limits por Endpoint

​Boas Práticas

​Upgrade de Plano

Ver Planos

WhatsApp

Limites por Plano

Headers de Rate Limit

Resposta de Limite Excedido

Estratégias de Tratamento

Exponential Backoff

Queue de Requisições

Rate Limits por Endpoint

Boas Práticas

Upgrade de Plano