Rate limits

Limites por plan

La API aplica limites de peticiones por minuto segun el plan de tu academia para garantizar un servicio estable para todos los usuarios:

• Trial (30 dias) — 60 peticiones por minuto.
• Pro ($49/mes) — 300 peticiones por minuto.
• Enterprise ($199/mes) — 1,000 peticiones por minuto.

Los limites se aplican por tenant (academia), no por usuario individual. Todas las peticiones de tu academia (de todos los usuarios y API keys) comparten la misma cuota.

Headers informativos

Cada respuesta de la API incluye headers que te informan sobre el estado de tu cuota en tiempo real:

• X-RateLimit-Limit — numero maximo de peticiones por minuto segun tu plan.
• X-RateLimit-Remaining — peticiones restantes en la ventana actual.
• X-RateLimit-Reset — timestamp Unix (en segundos) cuando se reinicia la ventana.

Monitorea estos headers en tu aplicacion para ajustar la frecuencia de peticiones y evitar alcanzar el limite.

Respuesta al exceder el limite

Cuando superas el limite, la API responde con:

• Codigo de estado: 429 Too Many Requests
• Body: { "error": "Rate limit exceeded", "retry_after": 32 }

El campo retry_after indica los segundos que debes esperar antes de enviar la siguiente peticion. No reintentes inmediatamente: espera el tiempo indicado.

Mejores practicas

• Implementa backoff exponencial — si recibes un 429, espera el tiempo indicado en retry_after. Si el siguiente intento tambien falla, duplica el tiempo de espera (1s, 2s, 4s, 8s...).
• Cachea respuestas — almacena localmente datos que no cambian frecuentemente como listas de cursos, categorias o configuracion de la academia. Esto reduce drasticamente el numero de peticiones.
• Usa paginacion eficiente — solicita solo los registros que necesitas con un limit apropiado. No pidas 100 registros si solo vas a mostrar 10.
• Agrupa operaciones — en lugar de hacer multiples peticiones individuales, usa los endpoints de lista con filtros para obtener todo lo que necesitas en una sola llamada.
• Webhooks en lugar de polling — para detectar cambios en pagos, inscripciones o suscripciones, configura webhooks en vez de consultar la API periodicamente. Los webhooks son mas eficientes y en tiempo real.

Solicitar aumento de limites

Si tu integracion requiere un limite mayor al de tu plan actual, tienes dos opciones:

• Actualizar tu plan — el plan Enterprise ofrece 1,000 peticiones por minuto, suficiente para la mayoria de las integraciones.
• Limites personalizados — para necesidades de alto volumen en el plan Enterprise, contacta al equipo de soporte desde Admin > Ajustes > Soporte describiendo tu caso de uso y el volumen esperado.

Preguntas frecuentes

• ¿Los rate limits se aplican por usuario o por academia?

  Por academia (tenant). Todas las peticiones de tu academia, sin importar que usuario o API key las haga, comparten el mismo contador de rate limit.

• ¿Las peticiones de webhook cuentan contra mi rate limit?

  No. Los webhooks entrantes (de Stripe, MercadoPago, etc.) son procesados por Didia y no cuentan contra el rate limit de tu API. Solo las peticiones que tu hagas a la API cuentan.

• ¿Que pasa si hago un burst de peticiones (muchas en pocos segundos)?

  El rate limit se mide por ventana de 1 minuto. Si tu plan permite 300 peticiones/minuto, puedes hacer las 300 en los primeros 10 segundos. Sin embargo, despues de agotar la cuota, tendras que esperar hasta que se reinicie la ventana.

• ¿Los endpoints publicos (sin autenticacion) tienen rate limit?

  Todos los endpoints de la API requieren autenticacion y estan sujetos a los rate limits de tu plan. No hay endpoints publicos sin limite.

• ¿El rate limit se reinicia al cambiar de plan?

  Si. Al actualizar tu plan (por ejemplo, de Pro a Enterprise), el nuevo limite se aplica inmediatamente. No necesitas esperar ni reiniciar nada.