Límites de tasa

La API limita el número de peticiones por ventana de tiempo. Superado el límite, la petición se rechaza con 429 sin llegar a ejecutarse: no consume cuota ni produce efectos.

La ventana es de un minuto y el contador arranca en cada minuto de reloj, no en la primera petición. Una ráfaga a caballo entre dos minutos se reparte entre ambos contadores.

Límite aplicable

El contador depende de si la petición lleva credenciales y del host que la atiende:

Varios clientes detrás de un mismo servidor no compiten por un único contador de IP: cada cuenta cuenta por separado con el límite de su plan. El techo por IP es una protección contra abuso, y lo comparten todas las claves que salen del mismo origen.

Determinadas operaciones aplican límites propios más estrictos por su costo o su sensibilidad, como el inicio de sesión, el envío de OTP y las difusiones, y los declaran en su página de referencia.

Límites por plan

Una cuenta sin plan, o con un plan sin valor propio, toma los del plan free. GET /v1/usage/limits devuelve los que aplican a la cuenta autenticada.

Webhooks

Las entregas hacia un mismo host destino tienen dos topes, y cada entrega necesita hueco en los dos:

Una entrega que no cabe no se pierde: se pospone y se reintenta con el calendario descrito en arquitectura de webhooks.

Respuesta 429

{
  "errors": [
    {
      "status": "429",
      "code": "rate_limit_exceeded",
      "detail": "Se superó el límite de peticiones."
    }
  ],
  "meta": { "version": "1.57.0", "api_version": "v1", "request_id": "e6f7a8b9c0d1" }
}

La respuesta incluye las cabeceras necesarias para reintentar sin adivinar:

En la API, un X-RateLimit-Limit de 1 200 identifica el techo por IP; cualquier otro valor es el límite por clave del plan.

Consumo en cada respuesta

Toda respuesta de la API a una petición con API key lleva X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset del contador por clave, no solo la 429. Remaining permite espaciar las llamadas antes de llegar al límite.

X-RateLimit-Limit: 240
X-RateLimit-Remaining: 187
X-RateLimit-Reset: 1790812860

El resto de las superficies, y las peticiones sin credenciales, emiten estas cabeceras únicamente en las respuestas 429. La repetición de una operación idempotente que se responde con el resultado guardado no pasa por el limitador y no las lleva.

Tratamiento recomendado

El valor de Retry-After es el único dato necesario para reintentar: esperar ese margen y repetir la petición. Reintentar antes vuelve a consumir contador y prolonga el bloqueo.

Los límites protegen el sistema frente a ráfagas, no frente al volumen total. El volumen mensual lo gobiernan la cuota del plan y sus propios códigos de error, descritos en la taxonomía de errores.