Skip to main content
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

RecursoLimite
Requisições/minuto40
Sessões ativas1
Mensagens/dia480
Webhooks1

​
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
HeaderDescrição
X-RateLimit-LimitTotal de requisições permitidas no período
X-RateLimit-RemainingRequisições restantes no período atual
X-RateLimit-ResetTimestamp 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()
);

​
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:
EndpointLimiteMotivo
POST /sessions5/minutoCriação de sessão é custosa
POST /messages/sendPor planoEvitar spam
GET /contacts/check10/minutoRate limit do WhatsApp
POST /groups3/minutoRate 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

1

Monitore os Headers

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

Implemente Caching

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

Use Webhooks

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

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

WhatsApp

Vendas e planos Enterprise: +55 87 8114-8453