Límites de API y picos de consumo: cómo evitar que una integración se bloquee
Una integración puede funcionar durante semanas y bloquearse justo al importar un catálogo, cerrar el mes o recuperar trabajo atrasado. La causa no siempre es una caída: quizá superó una cuota, concentró demasiadas llamadas o convirtió un error temporal en una tormenta de reintentos. Diseñar para los límites significa controlar cuánto trabajo entra, a qué ritmo sale y qué ocurre cuando el proveedor pide reducir la velocidad.
Lo esencial, antes de empezar
- Cuota, tasa, ráfaga y concurrencia limitan cosas distintas; una asignación mensual amplia no garantiza que un lote corto funcione.
- Dimensiona el pico normal y el pico de recuperación, incluidas las llamadas por trabajo y los reintentos observados.
- Ante un 429, interpreta la causa, respeta Retry-After y combina backoff con jitter y un máximo de intentos.
- La idempotencia, los estados explícitos y una cola visible evitan que la recuperación cree duplicados o pierda trabajo.
Cuota, tasa, ráfaga y concurrencia no son lo mismo
Una cuota limita consumo acumulado en una ventana; una tasa, la velocidad sostenida; una ráfaga, el pico breve que se tolera; y la concurrencia, las operaciones activas a la vez. AWS documenta un modelo de token bucket para tasa y ráfaga, con posibles respuestas 429 cuando se agota la capacidad disponible.
| Dato | Pregunta que resolver |
|---|---|
| Ventana | ¿Minuto, hora, día o facturación? |
| Ámbito | ¿Usuario, clave, aplicación, cuenta, IP o región? |
| Tasa y ráfaga | ¿Qué ritmo sostenido y qué pico admite? |
| Concurrencia | ¿Cuántas operaciones pueden ejecutarse a la vez? |
| Coste | ¿Todas las operaciones descuentan igual? |
| Señales | ¿Hay Retry-After, contadores o fecha de reinicio? |
| Ampliación | ¿Puede solicitarse o contratarse capacidad adicional? |
Dimensiona el pico, no solo el promedio
Ejemplo hipotético: 12.000 registros en una hora equivalen a unos 3,3 trabajos por segundo. Si el planificador libera el lote de golpe y 40 workers llaman a la API, la concurrencia real deja de parecerse al promedio. Tras una caída, además, coinciden la cola acumulada y los eventos nuevos.
| Escenario | Qué incluir |
|---|---|
| Normal | Llegada habitual, llamadas por trabajo y latencia mediana |
| Pico previsto | Campaña, cierre, importación o sincronización completa |
| Recuperación | Pendiente acumulado más tráfico nuevo |
| Degradado | Proveedor lento, 429, timeout y reintentos permitidos |
Calcula demanda base como trabajos por minuto × llamadas por trabajo ÷ 60. Añade después el reintento medido, no un margen oculto. Si 600 pedidos en diez minutos necesitan cuatro llamadas, la base es cuatro solicitudes por segundo; pruebas y documentación del proveedor dirán si existe margen.
Diseña una respuesta específica ante el error 429
- 01
Clasifica la causa
Lee código, cuerpo y cabeceras: tasa, cuota diaria, concurrencia y gasto pueden requerir acciones diferentes.
- 02
Respeta al proveedor
Usa Retry-After o la fecha de reinicio cuando exista; si no, aplica espera exponencial con jitter.
- 03
Limita intentos
Fija un máximo y mueve el trabajo agotado a revisión o a una cola de errores, sin marcarlo como completado.
- 04
Evita el efecto rebaño
El jitter y un limitador central impiden que cientos de tareas dormidas se reactiven a la vez.
La documentación de límites de GitHub distingue límites primarios y secundarios, recomienda respetar Retry-After y desaconseja insistir mientras persista el límite. Implementa la política del proveedor concreto, no una receta universal.
Cloudflare describe el 429 y el encabezado Retry-After como señales para reducir el ritmo. Si la carga necesita capacidad previsible, algunos servicios distinguen capacidad compartida y reservada, como muestra la documentación de throughput de Google Cloud. Contratar más capacidad no sustituye idempotencia, control de picos ni recuperación.
Usa idempotencia y una cola para recuperarte sin duplicados
Si crear una factura agota el tiempo, el cliente puede no saber si el proveedor la aceptó. Repetir sin control podría crear dos. Usa una clave idempotente cuando exista o una referencia única propia, y reconcilia antes de repetir una acción con efectos.
- Estados: pendiente, enviado, confirmado, reintentable, fallo definitivo y requiere revisión.
- Cola: capacidad máxima, prioridad, antigüedad visible, límite de concurrencia y alertas.
- Degradación: aceptar el trabajo como pendiente, usar datos cacheados o derivar a una persona.
- Aislamiento: un proveedor limitado no debe bloquear las demás integraciones.
Una cola no elimina el límite: lo convierte en una velocidad controlable. Si necesitas decidir entre eventos y consultas periódicas, revisa webhook frente a polling.
Prueba el sistema como puede fallar
- Ráfaga por encima del ritmo normal y lote liberado de golpe.
- 429 con y sin Retry-After, respuestas lentas, timeouts y 5xx.
- Reinicio de consumidor con trabajo en curso y eventos repetidos.
- Proveedor recuperado mientras siguen llegando eventos nuevos.
- Orden, idempotencia y tiempo máximo de vaciado de la cola.
| Métrica | Qué revela |
|---|---|
| Porcentaje limitado | Demanda que supera la capacidad actual |
| Antigüedad pendiente | Retraso real que ve el proceso |
| Intentos por operación | Coste y riesgo de tormenta |
| Duplicados detectados | Calidad de idempotencia y conciliación |
| Fallos a revisión | Carga humana residual |
Guarda los límites por proveedor, endpoint y credencial. La guía sobre cambios de versión de una API cubre el otro riesgo frecuente: que el contrato cambie aunque la capacidad siga disponible.
Checklist antes de poner la integración en producción
- Límites y ámbito documentados por endpoint y credencial.
- Concurrencia controlada y lotes repartidos en el tiempo.
- Reintentos con señal del proveedor, backoff, jitter y máximo.
- Idempotencia y reconciliación para operaciones con efectos.
- Cola con capacidad, antigüedad y alertas visibles.
- Pruebas de pico, recuperación y reinicio.
- Procedimiento de degradación y de solicitud de capacidad.
Fuentes y referencias
Documentación oficial y referencias de mercado consultadas para verificar los puntos que cambian con el tiempo.
