Límites de tasa de la API

Elido limita la tasa de la API por clave, no por espacio de trabajo. Eso significa que cada integración que construya puede saturar su propio límite sin dejar sin recursos a las demás. Este artículo cubre los límites por plan, los encabezados a leer y cómo retroceder limpiamente.

Los números#

Límites sostenidos por clave:

Plan	Por minuto	Ráfaga (Burst)
Free	60	120
Pro	600	1200
Business	6000	12000

La ráfaga es lo que puede exceder brevemente en una ventana de 10 segundos. El límite sostenido es el tope de estado estable al que se rellena el cubo (bucket).

No hay límites por punto final (endpoint): un GET /v1/links cuenta lo mismo que un POST /v1/links. Las únicas excepciones son:

• POST /v1/bulk-import — 5 importaciones activas por espacio de trabajo a la vez.
• POST /v1/links con un slug personalizado que colisiona con un slug existente — estos siguen contando pero no reembolsan el espacio en caso de conflicto.
• GET /v1/analytics/timeseries con interval=second — limitado a 60/minuto incluso en Business, porque la consulta subyacente de ClickHouse es más pesada.

Encabezados de respuesta#

Cada respuesta de la API incluye:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1747386240

X-RateLimit-Reset es una marca de tiempo Unix que le indica cuándo se vuelve a llenar el cubo por completo. Úselo para programar reintentos en lugar de retrasos fijos.

Cómo se ve un error 429#

Cuando excede el límite:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "API rate limit exceeded for this key",
  "retry_after_seconds": 12
}

Retry-After está en segundos. Espere ese tiempo y luego reintente. Los SDK hacen esto automáticamente con fluctuación (jitter); si está escribiendo un cliente HTTP puro, haga lo mismo.

Estrategia de retroceso (Backoff)#

Si está bombardeando la API (un trabajo masivo único, una carga de datos histórica), marque el ritmo de su cliente al límite de estado estable en lugar de la ráfaga. Un bucle ingenuo alcanza el tope de ráfaga, luego se detiene durante 50 segundos y luego vuelve a alcanzar la ráfaga, promediando un rendimiento peor que simplemente marcar el ritmo.

Pseudocódigo:

const limit = 600; // per minute
const delayMs = (60 * 1000) / limit; // 100ms between requests

for (const item of items) {
  await fetch(...);
  await sleep(delayMs);
}

Este patrón utiliza el 100% del límite con cero errores 429.

Concurrencia#

Las solicitudes concurrentes comparten el cubo. Si lanza 100 solicitudes paralelas desde un grupo de trabajadores en el plan Pro (600/min), las primeras 100 tienen éxito instantáneamente; luego, el cubo se rellena a razón de 10/seg. Su grupo de trabajadores debe apuntar a una tasa sostenida, no a una profundidad de cola.

Por clave vs por IP#

El cubo es por clave, no por IP. Si está usando la misma clave desde 10 máquinas, las 10 máquinas comparten el límite. Emita una clave por máquina si necesita 10 veces más margen.

La capa de IP tiene un límite separado y muy generoso (10,000/min/IP) destinado únicamente a detener clientes fuera de control. Nunca lo alcanzará en un uso normal; si lo hace, la respuesta es 429 con el cuerpo "error": "ip_rate_limited".

Las claves de idempotencia no evitan el límite#

Enviar la misma Idempotency-Key repetidamente sigue contando cada solicitud contra su cubo; podemos devolver la respuesta almacenada en caché sin realizar el trabajo subyacente, pero el recuento se incrementa. No use bucles con claves de idempotencia como estrategia de reintento.

Aumentar los límites#

Si su caso de uso realmente necesita más de 6000/min sostenidos, envíe un correo electrónico a support@elido.app con:

• Su ID de espacio de trabajo.
• El nombre de la integración.
• Tasa de solicitudes esperada en estado estable y pico.
• Qué puntos finales (para que podamos planificar la capacidad de los más pesados).

Otorgamos aumentos de límite por clave a clientes empresariales bajo contrato, generalmente dentro de un día hábil.

Solución de problemas#

De repente recibo errores 429 en una clave que solía funcionar. O su código comenzó a entrar en bucle (lo más común), o alguien más en el espacio de trabajo comenzó a usar la misma clave. Consulte la pestaña de Uso de la clave API en el panel para ver un gráfico por minuto.

Errores 429 en la primera solicitud del día. Los cubos del nivel Free se reinician en una ventana rodante, no a la medianoche UTC. Si probó el límite ayer a las 23:59 y no se ha rellenado por completo a las 00:01, la primera ráfaga seguirá limitada por la tasa. Espere 60 segundos.

X-RateLimit-Remaining es negativo. Exceso de ráfaga. El número le indica qué tan profundo está en negativo; multiplíquelo por 60/limit para obtener los segundos hasta que vuelva a cero.