Límites de uso
El límite de 60 pedidos por minuto por persona, cómo se cuenta y cómo reintentar después de un 429.
La API y el servidor MCP comparten un límite de pedidos para proteger el servicio. Esta página explica cómo se cuenta, qué contesta la API al pasarlo y cómo escribir un cliente que lo respete.
El límite
60 pedidos por minuto por persona.
- Por persona, no por key. Todas las keys de una misma persona suman al mismo contador, incluidas las que creó un cliente MCP. Dos integraciones con keys distintas de la misma persona se reparten los 60.
- REST y MCP juntos. Cada pedido a
/api/v1y cadaPOST /api/mcpcuentan contra el mismo contador. - Lecturas y escrituras por igual. Un
GETcuenta lo mismo que una acción. - Ventana fija de un minuto. La ventana arranca con el primer pedido y dura 60 segundos; al terminar, el contador vuelve a cero.
- Lo que no cuenta: un pedido con una key inválida (contesta
401antes de contar) yGET /openapi.json, que es público.
Cada persona tiene su propio contador: el uso de un compañero no te quita pedidos a ti.
Qué contesta al pasarlo
HTTP/1.1 429 Too Many Requests
Retry-After: 23
Content-Type: application/json
{ "error": "RATE_LIMITED", "retryAfterSeconds": 23 }retryAfterSeconds (y el header Retry-After, que es el mismo número) dice cuántos segundos faltan para que se abra la próxima ventana. El pedido rechazado no se ejecutó: puedes reintentarlo tal cual.
Cómo reintentar
Espera lo que dice Retry-After y vuelve a mandar el pedido. En las acciones, manda la misma Idempotency-Key en el reintento, así un pedido que sí llegó a ejecutarse no se repite (ver Idempotencia).
# curl reintenta ante un 429 (y otros errores transitorios) y respeta Retry-After
curl --retry 3 https://app.reclee.com/api/v1/job-posts \
-H "Authorization: Bearer $RECLEE_API_KEY"Cómo no llegar al límite
- Páginas grandes. Lee las listas con
pageSize=200: una lista de 1.000 filas son 5 pedidos en vez de 20. - Filtra en el servidor. Usa los filtros de cada ruta en vez de traer todo y filtrar en tu código.
- Acciones en lote. Varias acciones aceptan muchos ids a la vez (mover o descalificar candidatos, agregar a una vacante, guardar en el pool, enriquecer): una llamada con 50 ids es un solo pedido.
- Un ritmo parejo. Si tu proceso es largo, espacia los pedidos (uno por segundo nunca llega al límite) en lugar de mandar ráfagas.
- Una persona por integración intensiva. Como el límite es por persona, una integración que hace mucho tráfico conviene que use la key de una persona que no use el MCP al mismo tiempo.
Otros 429
Algunas operaciones tienen su propio freno, independiente del límite de pedidos. Todos contestan 429:
| Código | Qué frena |
|---|---|
RATE_LIMITED | También lo contesta una búsqueda o un enriquecimiento cuando el proveedor de datos externo pide esperar; trae retryAfterSeconds. |
EMAIL_RATE_LIMITED | El envío de emails (por ejemplo, invitaciones) alcanzó su tope. |
RESEND_TOO_SOON | Reenviar la misma invitación demasiado seguido. |
TOO_MANY | Demasiados CVs del workspace esperando ser leídos: espera a que la cola avance. |
Distinto de todo esto es el uso de IA: quedarse sin uso del plan contesta 402, no 429. Ver Créditos y uso.