Los límites de consumo en APIs PHP protegen la disponibilidad y el coste del servicio, pero una política mal diseñada puede interrumpir integraciones legítimas. Para acertar, no basta con fijar un número de peticiones por minuto: hay que identificar quién consume, qué operación ejecuta, qué recurso está en riesgo y cómo se comporta el tráfico real.
Un diseño eficaz combina límites adecuados al patrón de uso, contadores coherentes entre instancias y respuestas que permitan al consumidor recuperarse. También requiere observar el efecto de las reglas antes de endurecerlas, en especial cuando varios clientes comparten credenciales o dependen de recursos comunes.
Distingue tasa, cuota y concurrencia
Estos controles protegen frente a problemas distintos y no son intercambiables:
- Tasa de peticiones: limita cuántas solicitudes se aceptan en un intervalo breve. Ayuda a contener ráfagas o tráfico sostenido que satura la aplicación.
- Cuota acumulada: limita el consumo total durante un periodo mayor, por ejemplo una cantidad de operaciones por día o ciclo de facturación. Sirve para gobernar uso contratado o cargas costosas acumuladas.
- Concurrencia: limita cuántas operaciones están ejecutándose al mismo tiempo. Es útil cuando cada operación puede ocupar trabajadores, conexiones o recursos durante mucho tiempo.
Un cliente puede respetar una tasa y, aun así, acumular muchas operaciones largas simultáneas; también puede realizar pocas solicitudes que consuman una cuota diaria costosa. Define el control a partir del riesgo que quieres reducir y, si hacen falta varios, especifica cómo interactúan y cuál se aplica primero.
Decide qué identidad y recurso vas a limitar
La clave del límite debe representar una unidad de consumo que tenga sentido operativo. Según el producto, puede ser una credencial, un usuario, una organización, una aplicación cliente, una ruta o una combinación de ellos. Limitar sólo por dirección IP puede penalizar redes compartidas y no distingue bien a los consumidores autenticados; una IP puede servir como señal complementaria para tráfico anónimo o controles de seguridad.
Para clientes autenticados, conviene vincular la política a una identidad estable y aplicar aislamiento entre organizaciones. Una credencial compartida por varios sistemas puede ocultar quién genera una ráfaga: cuando sea posible, usa credenciales separadas o añade dimensiones que permitan atribuir el consumo. Evita incluir secretos sin transformar en claves de contadores o registros.
No todas las rutas tienen el mismo coste. Una consulta sencilla y una exportación extensa no deberían consumir necesariamente el mismo presupuesto. Puedes asignar pesos o políticas distintas a operaciones costosas, siempre que el criterio sea comprensible y consistente para los consumidores. Revisa también los límites del servicio: una API puede recibir pocas solicitudes y, aun así, saturar una dependencia compartida, como una base de datos o un proveedor externo.
Elige ventanas que reflejen el patrón de uso
Una ventana fija es sencilla de explicar, pero puede permitir una ráfaga al final de un intervalo seguida de otra al comienzo del siguiente. Una ventana deslizante reduce ese efecto a cambio de más trabajo de almacenamiento y cómputo. Un sistema de tokens permite ráfagas limitadas y una tasa media controlada; resulta útil cuando el tráfico legítimo llega en oleadas. La elección depende del patrón de consumo y de la precisión que se necesita.
No confundas un pico de actividad legítimo con abuso. Cargas programadas, sincronizaciones al inicio de jornada o reintentos tras una interrupción pueden concentrar solicitudes. Si el producto permite ráfagas, define explícitamente su tamaño y cuánto tarda en recuperarse el presupuesto. Para operaciones largas, limita además la concurrencia o aplica control de admisión antes de ocupar recursos escasos.
Los reintentos del cliente también importan. Si una respuesta temporal provoca reintentos inmediatos, el límite puede agravar el pico. Recomienda retroceso progresivo, idealmente con variación aleatoria, y define si operaciones repetidas con la misma clave de idempotencia cuentan como nuevas solicitudes o como una repetición segura.
Coordina contadores cuando PHP se ejecuta en varias instancias
Un contador guardado sólo en la memoria del proceso puede funcionar en una instancia, pero pierde coherencia al distribuir tráfico entre varias. Cada servidor podría aceptar una parte del límite y, en conjunto, excederlo. En despliegues con varias instancias, el estado debe coordinarse mediante un almacén compartido o un mecanismo equivalente con operaciones atómicas apropiadas.
Diseña también el comportamiento ante fallos del sistema de contadores. Si deja de estar disponible, rechazar todas las peticiones puede interrumpir clientes legítimos; aceptar todas puede exponer una dependencia crítica. La decisión depende del riesgo de la ruta: puede ser razonable fallar de forma distinta para una consulta de bajo impacto que para una operación que dispara costes elevados. Documenta el criterio y alerta sobre degradaciones.
Evita claves de contador demasiado generales, que mezclen organizaciones o rutas, y demasiado fragmentadas, que dificulten controlar el consumo total. Define caducidad y limpieza del estado para que las claves temporales no se acumulen indefinidamente. Comprueba que los cambios de configuración no reinicien o dupliquen contadores de forma inesperada.
Comunica el rechazo como parte del contrato de API
Cuando se alcanza un límite, devuelve un estado HTTP coherente con el contrato de la API —habitualmente 429 Too Many Requests para una limitación de tasa— y un cuerpo estructurado que identifique el tipo de límite sin revelar información interna. Si la operación se rechaza por otra causa, no uses ese estado de forma engañosa.
Incluye orientación útil para recuperarse, como el momento estimado para volver a intentar o los datos de límite y consumo que el contrato haya definido. Si envías Retry-After, asegúrate de que represente una espera válida. Mantén respuestas consistentes entre rutas y evita exponer contadores de otros clientes. Los consumidores deben poder distinguir un rechazo temporal de errores de autenticación, validación o disponibilidad.
Observa el impacto y ajusta con evidencia
Registra solicitudes aceptadas y rechazadas, identidad o segmento de cliente de forma segura, ruta, política aplicada y motivo. Mide también latencia, concurrencia y presión sobre dependencias relevantes. No guardes credenciales ni datos personales innecesarios; utiliza identificadores protegidos o agregados cuando basten para el análisis.
Un aumento de rechazos no demuestra por sí solo que el umbral sea demasiado estricto. Busca patrones: clientes afectados, horarios, rutas, duración de operaciones y reintentos posteriores. Investiga señales de falsos positivos, como rechazos concentrados en organizaciones con credenciales compartidas o en tareas programadas. Ajusta una variable cada vez y conserva una forma de revertir el cambio.
Introduce la política gradualmente
Antes de hacer cumplir un límite, evalúa la política con datos de uso y prueba escenarios representativos. Si la arquitectura lo permite, registra qué solicitudes se habrían rechazado sin bloquearlas; esta observación no sustituye las pruebas de carga ni garantiza que los datos históricos anticipen todos los picos.
- Define el riesgo que quieres controlar y si corresponde una tasa, una cuota, concurrencia o una combinación.
- Asigna límites por identidad y recurso, y verifica el aislamiento entre usuarios y organizaciones.
- Prueba ráfagas, operaciones lentas, reintentos, credenciales compartidas y fallos del almacén de contadores.
- Comprueba que varias instancias aplican el límite de forma coordinada y que el estado temporal se limpia.
- Valida la respuesta de rechazo, la orientación para reintentar y la compatibilidad con los consumidores actuales.
- Monitoriza rechazos, latencia y dependencias; comunica cambios que puedan afectar a las integraciones.
Los límites de consumo en APIs PHP deben proteger tanto la plataforma como la continuidad de los clientes. La mejor política no es la más estricta, sino la que controla el riesgo con reglas atribuibles, respuestas previsibles y evidencia suficiente para corregir efectos no deseados.
