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.
Gestiona una respuesta 429 sin perder la solicitud
Un código de estado 429 no es el mismo tipo de fallo que un 400 o un 404. Significa que la solicitud estaba bien formada y habría funcionado, pero tu cuota del periodo actual está agotada.
Cómo es la respuesta
HTTP/1.1 429 Too Many Requests
X-Quota-Limit: 2500
X-Quota-Used: 2500
X-Quota-Free-Remaining: 0
X-Credits-Remaining: 0.00
X-Quota-Reset: 2026-09-22T00:00:00Z
{
"status": "error",
"error": {"code": "quota_exceeded", "message": "Daily quota exceeded"}
}No descartes la solicitud
El error más común es tratar un 429 igual que un 400, registrarlo como fallo y seguir adelante. La consulta subyacente que querían el usuario o tu script sigue siendo perfectamente válida, solo necesita ejecutarse más tarde o con otras credenciales. Pon el contenido original de la solicitud en una cola de reintentos en lugar de descartarlo.
Leer la hora de reinicio
El encabezado X-Quota-Reset de la respuesta 429 te indica exactamente cuándo se reinicia la cuota diaria. Un trabajo en segundo plano puede esperar hasta esa hora y luego reanudar la cola, en lugar de consultar repetidamente o adivinar un intervalo fijo de reintento.
Un segundo escenario para el que conviene prepararse
Un 429 no siempre significa que se haya agotado toda la cuota del día. Si X-Key-IPs-Used ha alcanzado X-Key-IPs-Limit, una clave puede ser rechazada temporalmente desde una nueva dirección de origen aunque las solicitudes desde sus direcciones habituales sigan funcionando. Comprobar qué encabezado explica realmente el 429, el agotamiento de la cuota o un límite de espacios de IP, cambia la solución: en un caso, esperar a un reinicio, y en el otro, reducir el número de máquinas distintas que usan la misma clave.
Dos formas de superar el límite ahora mismo
Si esperar no es aceptable, hay dos opciones inmediatas: recargar crédito prepago a 0,0001 € por solicitud, o pasar a una clave Unlimited por 50 € al mes si se trata de un patrón recurrente y no de un pico puntual. Ambas eliminan el techo diario que provocó el 429 en primer lugar.
Distinguir los límites de la clave de los límites de la red
Como la cuota gratuita se comparte en toda una /24 en IPv4 o una /48 en IPv6, un 429 puede producirse por el tráfico de otras direcciones de la misma red, no solo por el uso de tu propia clave. Comprueba X-Quota-Network-Used junto con X-Quota-Used para distinguir las dos situaciones antes de decidir si mejorar la clave arreglará realmente algo.
Un error que conviene evitar
Reintentar una solicitud fallida de inmediato, en un bucle cerrado, en cuanto vuelve un 429 solo añade más llamadas fallidas sobre una cuota que ya está agotada, sin acercarte en absoluto a una solicitud que funcione. Espera hasta la hora de reinicio indicada en el encabezado, o un retraso fijo razonable si el código no lee encabezados, en lugar de volver a bombardear el endpoint de inmediato.
Tratar un 429 como "inténtalo de nuevo en breve" en lugar de "esto ha fallado" mantiene una cola avanzando sin problemas a través de un reinicio de cuota en lugar de perder trabajo. Los detalles sobre la forma de los errores en toda la API están en la página de errores, y las opciones de cuota actuales, en la página de precios.