Copy page

Documentación

Límites de peticiones

La API de Aleluya aplica rate limiting para garantizar estabilidad y acceso equitativo. Los límites se evalúan en una ventana fija de 60 segundos y se aplican de forma independiente por IP y por usuario.

---

Límites

Dimensión	Límite
Por dirección IP	150 peticiones / minuto
Por usuario autenticado	150 peticiones / minuto

Ambos límites se evalúan de forma independiente — si tu IP tiene múltiples usuarios, cada uno tiene su propio contador.

---

Respuesta al exceder el límite

Cuando superas cualquiera de los límites, la API responde con 429 Too Many Requests hasta que la ventana se restablezca.

Ejemplo de respuesta:

Code
{
  "error": [
    {
      "code": "0001",
      "message": "Has excedido el límite de solicitudes permitidas. Por favor, intenta de nuevo más tarde.",
      "object": "rate_limit",
      "index": 0
    }
  ]
}

Headers de rate limiting

Cada respuesta incluye estos headers para que puedas monitorear tu consumo:

Header	Descripción
RateLimit-Limit	Límite total de peticiones por minuto
RateLimit-Remaining	Peticiones restantes en la ventana actual
RateLimit-Reset	Timestamp Unix de cuándo se resetea el contador

---

Cómo manejar el límite

Reintentos con backoff exponencial

Cuando recibas un 429, espera antes de reintentar. Aumenta el tiempo de espera en cada intento para no seguir saturando la API:

Intento	Espera sugerida
1	1 segundo
2	2 segundos
3	4 segundos
4	8 segundos

Si tras varios intentos sigues recibiendo 429, revisa si tienes múltiples procesos haciendo peticiones en paralelo al mismo usuario o IP.

Buenas prácticas

• Monitorea RateLimit-Remaining antes de enviar ráfagas de peticiones.
• Espacia las peticiones cuando proceses lotes grandes apunta a no más de 2 peticiones por segundo para tener margen.
• Cachea respuestas que no cambian con frecuencia (sectores económicos, tipos de documento, etc.) en lugar de consultarlas en cada ejecución.
• Centraliza las llamadas a la API en un solo cliente para evitar que múltiples procesos compitan por el mismo límite.