Controla el uso de tu clave antes de alcanzar un límite
Vigilar las cabeceras de cuota sobre la marcha te indica cuándo te acercas a un límite, mucho antes de que se rechace realmente una solicitud.
Interpreta correctamente las cabeceras X-Quota-Used y X-Quota-Limit
Cada respuesta de la API, sea correcta o no, incluye un conjunto de cabeceras que describen exactamente en qué punto estás respecto a tu cuota. Leerlas correctamente significa entender qué cuenta cada una.
El par principal
X-Quota-Limit es el tamaño de tu cuota actual, ya sea la cuota diaria gratuita o el límite efectivo con un paquete Unlimited. X-Quota-Used es el número de solicitudes que se han contado contra esa cuota hasta ahora en el periodo actual. No hace falta restar una de otra a mano, ya que X-Quota-Free-Remaining ya lo hace por ti.
HTTP/1.1 200 OK
X-Quota-Limit: 2500
X-Quota-Used: 1840
X-Quota-Free-Remaining: 660
X-Quota-Network-Used: 1840
X-Credits-Remaining: 0.00
X-Key-IPs-Used: 1
X-Key-IPs-Limit: 3
X-Quota-Reset: 2026-09-22T00:00:00ZUso de la clave frente a uso de la red
X-Quota-Used refleja el uso ligado a tu clave, mientras que X-Quota-Network-Used refleja el uso de la red a la que perteneces, ya que la cuota gratuita se comparte entre todas las direcciones IPv4 del mismo /24 y todas las direcciones IPv6 del mismo /48, haya o no una clave de por medio. Si una clave se llama desde varios servidores detrás del mismo bloque de direcciones, la cifra de la red subirá más rápido de lo que cualquier servidor esperaría por su propio tráfico.
El par de espacios de IP
X-Key-IPs-Used y X-Key-IPs-Limit describen algo completamente distinto: cuántas direcciones de origen distintas han usado recientemente esta clave concreta, frente al límite móvil de dos o tres direcciones permitidas por clave. Una clave llamada desde un único servidor mostrará aquí un 1 constante. Una clave compartida entre varios servidores sin relación, o copiada en un script que acaba ejecutándose desde muchas máquinas, se irá acercando al límite, algo que conviene vigilar por separado de tu cuota de solicitudes, ya que puede bloquear una clave aunque queden muchas solicitudes gratuitas.
Crédito y hora de reinicio
X-Credits-Remaining muestra tu saldo prepago una vez que has superado la cuota gratuita y estás consumiendo crédito a 0,0001 € por solicitud. X-Quota-Reset te indica exactamente cuándo se reinicia la cuota diaria actual, lo que es más fiable que suponer una hora fija basándote en tu propio reloj.
Qué construir a partir de estas cabeceras
Un panel, una alerta o simplemente una línea de registro que lea estas cabeceras después de cada llamada te da una imagen del uso en tiempo real sin necesidad de una llamada de informes aparte, ya que las cifras llegan en la respuesta que ya has recibido. Leerlas no cuesta nada extra, porque viajan con cada solicitud que ya estabas enviando, tanto si esa solicitud salió bien como si devolvió un error.
Un error que conviene evitar
Leer estas cabeceras solo cuando algo va mal significa que te enteras de un problema de cuota en el mismo momento que tus usuarios. Registra al menos X-Quota-Free-Remaining y X-Credits-Remaining de forma periódica, o después de cada llamada en una integración con poco tráfico, para que un avance lento hacia el límite aparezca como una tendencia en un panel y no como una tanda repentina de respuestas 429.
Leer las cabeceras de cuota en cada respuesta, en lugar de esperar a un 429 para darte cuenta de un problema, marca la diferencia entre una ralentización controlada y una que te pilla por sorpresa. La lista completa de cabeceras está documentada en la página de límites de frecuencia.