Límites de velocidad de API de terceros: lista de verificación previa al despliegue para aplicaciones autoalojadas

Por qué los límites de velocidad de las API deben formar parte de la planificación de preparación de la aplicación

Una aplicación autoalojada puede estar completamente accesible y en buen estado mientras un flujo de trabajo crítico sigue sin poder completarse porque una API externa está limitando sus solicitudes. Esto convierte la cuota de un proveedor, las reglas de concurrencia, las restricciones de endpoints y las instrucciones de reintento en parte de la preparación para producción, y no en un detalle que descubrir después de que los usuarios empiecen a depender de la integración.

HTTP 429 significa que un cliente ha enviado demasiadas solicitudes en un periodo determinado. El estándar HTTP permite, pero no exige, un campo de respuesta Retry-After. Tampoco define cómo identifica el proveedor a la parte que está siendo limitada ni cómo se contabilizan las solicitudes. Un límite puede aplicarse a una credencial, cuenta, espacio de trabajo, dirección IP, endpoint u otro ámbito definido por el proveedor.

Trate cada dependencia saliente importante como un recurso compartido y finito. La pregunta práctica no es simplemente «¿Esta aplicación es compatible con la API?». Es «¿Puede este despliegue seguir siendo útil cuando el uso normal, la demanda máxima, el procesamiento en segundo plano y el trabajo de recuperación consumen simultáneamente los límites del proveedor?»

• Incluya las API externas en las revisiones de riesgos de lanzamiento junto con DNS, copias de seguridad, control de acceso y configuración de la aplicación.
• Evalúe la consecuencia empresarial del trabajo externo retrasado, parcial o fallido.
• Establezca expectativas para los usuarios antes del lanzamiento cuando una acción pueda quedar en cola o retrasarse por un límite del proveedor.

Empiece por evidencia oficial, no por una sola cifra de cuota

Cree un registro de evidencia para cada proveedor crítico. Dé preferencia a la documentación oficial de la API del proveedor y conserve la URL de la documentación, la fecha de consulta, el método de autenticación y el contexto del plan o cuenta que se aplique a su despliegue. No se base en un resumen web general, una respuesta histórica de un foro o una cuota observada en la cuenta de otro equipo.

La documentación de GitHub, por ejemplo, distingue entre límites primarios, límites específicos de endpoints, un límite independiente para GraphQL y límites secundarios que pueden incluir concurrencia y actividad en endpoints. Este es un modelo útil: una integración puede estar restringida por varias reglas superpuestas.

Registre el comportamiento de respuesta del proveedor. Cuando estén disponibles, identifique las cabeceras de límite de velocidad, los tiempos de restablecimiento y el comportamiento de Retry-After. GitHub y Docker Hub documentan señales de respuesta que exponen el estado del límite, la capacidad restante o la información de restablecimiento. Estas señales son operativamente más útiles que estimar mediante conjeturas a partir de una cifra genérica de solicitudes por minuto.

• URL de la documentación oficial y fecha en que se comprobó.
• Clases de límites: presupuesto general, límites específicos de endpoints, concurrencia, reglas basadas en coste, límites de descargas o controles contra abuso.
• Identidad y ámbito sujetos al límite: cuenta, token, usuario, espacio de trabajo, dirección IP, endpoint u otra clave.
• Requisitos de autenticación y si esta cambia la atribución o el presupuesto.
• Cabeceras de respuesta, semántica de restablecimiento, instrucciones de Retry-After y vía de escalado o soporte.
• Cualquier entorno de pruebas, sandbox o endpoint de staging aprobado.

Mapee cada dependencia de API saliente y ruta de llamada

Inventaríe las dependencias por flujo de trabajo, no solo por proveedor. Un mismo proveedor puede utilizarse para una búsqueda orientada al usuario, una sincronización programada, un proceso de recuperación de webhooks y una canalización de despliegue. Estas rutas pueden utilizar distintas credenciales, endpoints, volúmenes de solicitudes y niveles de urgencia.

Mapee primero la actividad interactiva: acciones iniciadas desde la interfaz de la aplicación, como que un usuario guarde un registro, recupere datos o envíe una solicitud a un servicio de IA o de datos. Después, mapee el trabajo en segundo plano: sincronización programada, procesamiento por lotes, informes recurrentes, indexación, importaciones, entrega de exportaciones, notificaciones y tareas de mantenimiento.

No omita el trabajo activado por entradas. Un webhook es entrante para su aplicación, pero procesarlo suele generar llamadas salientes para recuperar detalles o actualizar otro sistema. Las descargas de imágenes y las extracciones desde un registro de contenedores también pueden ser dependencias externas durante el despliegue, las actualizaciones automatizadas o el escalado. Docker documenta por separado los controles de API, extracción de imágenes y prevención de abuso, por lo que no deben tratarse como un único límite intercambiable.

• Acciones interactivas de usuarios y sus llamadas posteriores.
• Tareas programadas, sus calendarios y el solapamiento previsto.
• Procesamiento activado por webhooks y gestión de reentregas.
• Bucles de sondeo y comprobaciones de estado.
• Paginación, importaciones, exportaciones, indexación y relleno histórico.
• Llamadas a servicios de IA, enriquecimiento de datos, notificaciones y archivos.
• Extracciones de imágenes de contenedores y otras solicitudes externas en tiempo de despliegue.

Identifique la unidad que realmente está limitada

Una cuota numérica no es operativa hasta que sepa quién la comparte. Una solicitud no autenticada puede estar limitada por la dirección IP de origen, mientras que las solicitudes autenticadas pueden presupuestarse respecto a credenciales u otra identidad de cuenta. GitHub documenta ambos patrones y señala que distintos métodos de autenticación pueden afectar al mismo presupuesto restante.

Las credenciales compartidas son especialmente importantes en entornos autoalojados. Producción, staging, una sesión local de resolución de problemas, varias instancias de aplicación y equipos distintos pueden consumir sin querer el mismo presupuesto del proveedor. A la inversa, un proveedor puede agrupar actividad por dirección IP, haciendo que aplicaciones que de otro modo serían independientes compitan entre sí.

Para cada flujo de trabajo, anote la unidad sujeta a límite según la documentación del proveedor y, después, enumere todos los actores que pueden consumirla. Si la respuesta es incierta, trátela como un elemento de lanzamiento sin resolver en vez de asumir que cada usuario recibe una asignación independiente.

• ¿Qué credencial, cuenta, espacio de trabajo o identidad IP recibe el cargo?
• ¿REST, GraphQL u otras superficies de API tienen presupuestos separados?
• ¿Hay endpoints con límites más estrictos o modelos de coste distintos?
• ¿Qué entornos e instancias comparten el mismo presupuesto?
• ¿La agregación del proveedor basada en IP puede generar contención compartida?
• ¿Quién es responsable de la credencial y puede rotarla o sustituirla?

Estime el tráfico normal, máximo y de recuperación sin falsa precisión

Elabore una estimación sencilla por rangos para cada flujo de trabajo. Use entradas observables: usuarios activos probables, acciones por usuario, llamadas por acción, ejecuciones programadas, páginas por conjunto de resultados, workers y comportamiento de reintento esperado. El objetivo es revelar los impulsores de demanda y los requisitos de margen, no afirmar un número futuro preciso de solicitudes.

Separe la operación normal de la operación en picos. Los picos suelen provenir de una campaña, una afluencia al inicio de la jornada, una importación grande, una programación por lotes alineada a la hora o el inicio simultáneo de muchos workers. Incluya el peor solapamiento plausible: un pico interactivo mientras las tareas programadas y el procesamiento de webhooks están activos.

Después, estime la demanda de recuperación. Tras una interrupción o una ventana de mantenimiento, las colas pueden vaciarse, los webhooks pueden volver a entregarse y las sincronizaciones pueden ponerse al día. La recuperación suele ser más irregular que el uso ordinario. Un despliegue que encaja en el presupuesto de estado estable puede aun así fallar cuando intenta recuperar el trabajo perdido.

• Rango normal: usuarios habituales, programaciones y volúmenes de datos.
• Rango máximo: ráfagas previstas y cargas de trabajo solapadas.
• Rango de recuperación: acumulación pendiente, reentregas, sincronizaciones de puesta al día y reprocesamiento.
• Solicitudes por evento de negocio, incluidas las llamadas de búsqueda posteriores.
• Concurrencia: número de workers o solicitudes activas al mismo tiempo.
• Decisión sobre el margen: reducir la demanda, distribuir las programaciones, solicitar un límite aprobado más alto o aceptar un retraso por cola.

Cuente los multiplicadores: reintentos, paginación, sondeo, importaciones y workers simultáneos

La unidad aparente de trabajo rara vez es la unidad de solicitud. Una solicitud que devuelve una colección grande puede requerir una secuencia de solicitudes de página. La documentación de la API REST de GitHub describe resultados paginados y enlaces a la página siguiente; toda dependencia paginada debe estimarse por las páginas recuperadas, no por una búsqueda o sincronización visible para el usuario.

Los reintentos multiplican el tráfico precisamente cuando un proveedor ya está bajo presión. Una política de reintentos debe respetar la hora de restablecimiento o el valor Retry-After indicados por el proveedor. Para fallos persistentes, use reintentos limitados con esperas crecientes y una ruta explícita de fallo final. Un bucle de reintentos sin límite convierte un límite temporal en una cola creciente, capacidad desperdiciada y resultados poco claros para el usuario.

El sondeo merece el mismo escrutinio. Pregunte si un evento o webhook puede sustituir comprobaciones frecuentes de estado, si puede aumentarse el intervalo y si muchos workers están comprobando el mismo estado de forma independiente. Cuando se admiten, las solicitudes condicionales pueden evitar consumo innecesario: GitHub documenta que las solicitudes condicionales autenticadas que devuelven 304 Not Modified no cuentan para su límite de velocidad principal.

Los workers simultáneos pueden generar presión repentina incluso cuando el volumen diario total es modesto. Aplique límites tanto a la tasa de nuevas llamadas salientes como al número de workers. Escalone las programaciones y use colas cuando la arquitectura de la aplicación o integración lo permita.

• Multiplique las operaciones de listado por el número esperado de páginas, incluidas las comprobaciones de la última página cuando corresponda.
• Use la espera indicada por el proveedor y, después, backoff exponencial cuando sea apropiado.
• Limite los reintentos y muestre un estado de fallo final para revisión o recuperación posterior.
• Evite el sondeo que duplica trabajo ya disponible mediante eventos o webhooks.
• Use solicitudes condicionales cuando el proveedor y el endpoint las admitan.
• Limite la concurrencia de workers y escalone el inicio de los lotes.

Decida cómo se comparten las credenciales entre entornos e instancias

El diseño de credenciales es diseño de capacidad. Un token de producción compartido puede simplificar la administración, pero también crea un presupuesto de límite de velocidad compartido y un mayor radio de impacto ante demanda accidental. Las credenciales independientes pueden aislar la actividad de desarrollo o staging, pero solo si el modelo de atribución documentado por el proveedor hace que esa separación sea significativa.

No utilice credenciales de producción para scripts exploratorios, pruebas locales o un entorno de staging, salvo que ese uso compartido sea deliberado, esté documentado y sea seguro. Una prueba de despliegue, migración de datos o sesión de depuración puede consumir capacidad necesaria para los flujos de trabajo en vivo.

Documente dónde se utiliza cada credencial, qué identidad representa, quién puede cambiarla y qué otras cargas de trabajo consumen la misma cuota. Verifique también que la rotación de credenciales no interrumpirá silenciosamente el trabajo en cola ni la validación de webhooks.

• Separe las credenciales de producción, staging y desarrollo cuando las reglas del proveedor y la gobernanza lo permitan.
• Restrinja quién puede crear, sustituir o exponer credenciales.
• Enumere cada instancia de aplicación, worker y script que utiliza cada credencial.
• Compruebe si un cambio de credencial afecta a trabajos en cola, verificación de webhooks o configuración de callbacks.
• Evite tratar una credencial como privada si varios sistemas comparten su presupuesto de límite de velocidad.

Defina el comportamiento aceptable cuando se alcance el límite

Una política de límite de velocidad debe describir la experiencia del usuario y del sistema, no solo la respuesta HTTP. Para cada flujo de trabajo, decida si la acción correcta es esperar, poner el trabajo en cola, reducir el alcance solicitado, notificar al usuario, fallar de forma segura o seguir una ruta alternativa aprobada por el proveedor. La elección correcta depende de si la acción es urgente, repetible, idempotente y crítica para el negocio.

Para las solicitudes interactivas, un mensaje claro de finalización retrasada puede ser mejor que intentos inmediatos repetidos. Para el trabajo por lotes, puede ser apropiada una cola duradera y un comportamiento de reanudación controlado. Para un paso de enriquecimiento no esencial, puede ser aceptable guardar el registro principal y marcar el enriquecimiento como pendiente. No sustituya un proveedor o fuente de datos por otro a menos que esa alternativa esté aprobada para los requisitos de datos, coste, seguridad y calidad del flujo de trabajo.

Evite asumir que una función de reintentos del proxy inverso resolverá la limitación de una API ascendente. Traefik documenta que su middleware Retry aborda fallos al contactar con un backend en la capa de transporte TCP y se detiene una vez que un backend responde, independientemente del estado HTTP. Una respuesta 429 de una API ascendente requiere gestión en la capa de aplicación o integración, diseñada según las instrucciones de ese proveedor. De forma similar, un limitador de velocidad entrante controla el tráfico dirigido a su servicio; no revela ni aumenta la cuota de un proveedor externo.

• Indique el comportamiento elegido para cada flujo de trabajo cuando se agote la capacidad.
• Conserve un registro duradero del trabajo que esté en cola, incompleto o requiera revisión.
• Haga idempotentes las operaciones reintentables o protéjalas contra efectos secundarios duplicados.
• Use alternativas solo cuando estén aprobadas explícitamente y se hayan probado.
• Muestre un estado útil a usuarios y operadores en lugar de ocultar fallos repetidos.