Rate Limits

La API de Plazbot aplica un límite de uso por workspace para garantizar la estabilidad de la plataforma. El límite usa un modelo token bucket: permite rafagas cortas y castiga solo el uso sostenido por encima del límite.

Límites

El límite se comparte entre todas las integraciones que usan el mismo workspace (SDK, API REST directa, MCP, workers).

Headers de respuesta

Cada respuesta de la API incluye headers informativos para que tu integración pueda autorregularse:

Respuesta al exceder el límite

Cuando el límite se excede, la API responde 429 Too Many Requests con el header Retry-After (segundos a esperar antes de reintentar):

01{
02  "success": false,
03  "code": 429,
04  "errorCode": "RATE_LIMIT_EXCEEDED",
05  "message": "Rate limit excedido. Máximo 120 requests por minuto por workspace."
06}

Buenas prácticas

• Respeta Retry-After: al recibir un 429, espera los segundos indicados antes de reintentar. No reintentes en loop inmediato.
• Usa backoff exponencial en procesos batch: si un 429 se repite, duplica la espera en cada reintento.
• Página con pageSize=100: para recorrer contactos usa el tamaño de página máximo y minimiza la cantidad de llamadas (ver Contactos - Paginación).
• Cachea lo que no cambia: variables del workspace, etiquetas y fases cambian poco; no las consultes en cada request.

Ejemplo de manejo de 429

01async function callWithRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
02  for (let attempt = 0; ; attempt++) {
03    try {
04      return await fn();
05    } catch (error: any) {
06      const status = error?.response?.status;
07      if (status !== 429 || attempt >= maxRetries) throw error;
08 
09      const retryAfter = Number(error.response.headers["retry-after"] ?? 5);
10      await new Promise((r) => setTimeout(r, retryAfter * 1000 * (attempt + 1)));
11    }
12  }
13}