1. Introducción
En integraciones con la API de QuickBooks Online, es común encontrar errores relacionados con límites de uso. Uno de los más frecuentes es:
Intuit.Ipp.Exception.ThrottleExceededException: Throttle Exception was thrown
Este error indica que la aplicación ha excedido los límites de consumo de la API definidos por la plataforma. El objetivo de este documento es explicar el contexto del error, sus causas y las estrategias recomendadas para su mitigación.
2. Descripción del problema
2.1 Definición del error
El error ThrottleExceededException ocurre cuando una aplicación supera los límites de llamadas permitidas por la API en un periodo determinado. Generalmente se manifiesta junto con un código HTTP:
429 Too Many Requests
Este mecanismo de control (throttling) se implementa para garantizar estabilidad, rendimiento y equidad entre todos los usuarios de la plataforma.
3. Límites de la API
Para los endpoints de producción de QuickBooks Online, los límites actuales son:
500 solicitudes por minuto por Realm ID
10 solicitudes concurrentes por segundo por Realm ID y aplicación
40 solicitudes batch por minuto por Realm ID
Máximo de 30 operaciones por solicitud batch
3.1 Cambios relevantes
El 10 de agosto de 2024, se activó la validación estricta de límites concurrentes y batch.
El 16 de agosto de 2024, se desactivó temporalmente para análisis.
El 18 de noviembre de 2024, los límites fueron reactivados de forma definitiva.
Aplicaciones que no cumplan con estos límites seguirán funcionando, pero generarán errores 429 de forma recurrente.
4. Causas del error
El error puede originarse por las siguientes situaciones:
Exceso de solicitudes en un corto periodo de tiempo
Demasiadas solicitudes concurrentes
Uso ineficiente de consultas (queries sin filtros)
Sincronizaciones masivas sin control de frecuencia
Uso incorrecto de solicitudes batch
5. Impacto en el sistema
Cuando ocurre este error:
Las solicitudes fallan temporalmente
Puede haber pérdida de sincronización de datos
Se incrementa la latencia de la aplicación
Se afecta la experiencia del usuario final
6. Recomendaciones y buenas prácticas
Para evitar el error ThrottleExceededException, se recomienda:
6.1 Optimización de llamadas
Realizar solicitudes solo cuando sea necesario
Evitar polling constante innecesario
6.2 Control de concurrencia
Limitar a máximo 10 solicitudes simultáneas por segundo
Implementar colas o mecanismos de control (queueing)
6.3 Uso eficiente de consultas
Aplicar filtros adecuados
Implementar paginación
Reducir el volumen de datos por solicitud
6.4 Manejo de sincronización
Utilizar webhooks para detectar cambios
Implementar CDC (Change Data Capture) en lugar de consultas completas
6.5 Implementación de reintentos
Manejar errores 429 con lógica de retry
Usar exponential backoff para reintentos progresivos
7. Ejemplo de estrategia de mitigación
Una estrategia básica incluye:
Detectar el error 429
Esperar un tiempo antes de reintentar
Reducir la tasa de solicitudes
Registrar eventos para monitoreo
8. Soporte y monitoreo
Si el problema persiste:
Revisar métricas de uso de la API
Identificar qué Realm ID excede los límites
Contactar al equipo de soporte de QuickBooks para obtener datos específicos
9. Conclusión
El error Intuit.Ipp.Exception.ThrottleExceededException no representa una falla del sistema, sino un mecanismo de protección de la API. Su correcta gestión requiere optimización del consumo, control de concurrencia y estrategias eficientes de sincronización.
Adoptar buenas prácticas no solo evita errores, sino que mejora significativamente el rendimiento y escalabilidad de la aplicación.
Comments
0 comments
Please sign in to leave a comment.