Guías
Límites de uso
Peticiones por clave
Cada clave tiene sus propios límites:
- 60 peticiones por minuto, con ráfagas de hasta 20 seguidas.
- 5.000 peticiones al día.
Si tienes varias integraciones, dale a cada una su clave: así una no agota la cuota de las demás.
Al superarlos
La API responde 429 rate_limited con la cabecera Retry-After, en segundos enteros:
HTTP/1.1 429 Too Many Requests
Retry-After: 12{ "error": { "code": "rate_limited", "message": "Rate limit exceeded. Retry later." } }Espera al menos esos segundos antes de reintentar y, si vuelve a pasar, aumenta la espera cada vez.
No hay cabeceras informativas X-RateLimit-*: no sabrás cuánta cuota te queda hasta que llegue el
429.
Qué peticiones cuentan
- No cuentan las que fallan por la clave (
401 invalid_api_key) ni por falta de permiso (403 insufficient_scope). - Cuentan todas las demás, incluidos los errores
404,409y422.
Cuidado
Un script que reintenta en bucle una petición no válida agota su cuota igual que uno que funciona.
Reintenta solo los 429 y los 500; un 4xx no se arregla repitiéndolo.
Tamaño del cuerpo
Los cuerpos de POST y PATCH admiten hasta 64 KB. Si pasas de ahí, la respuesta es
422 body_too_large.