Límites, uso y auditoría de una clave
Cuántas peticiones admite una clave por hora y en ráfaga, cómo saber lo que le queda y dónde queda anotado todo lo que hace.
Actualizado el . 3 min de lectura
Incluido en todos los planes. Ver precios
Cada clave tiene su propio cupo de peticiones por hora, que eliges al crearla, además del freno de ráfagas que tiene toda la API. Lo que hace la clave queda contado en su ficha y anotado en la auditoría a nombre de su persona responsable.
Los límites
Límites de una clave
- Peticiones por hora
- 1.000por hora
- Por defecto. Se cambia entre 10 y 10.000 al crearla o editarla.
- Ráfagas
- 600al minuto por ruta
- Freno general de toda la API, contado por clave.
- Claves no válidas desde una dirección IP
- 30al minuto
- Inexistentes, revocadas o caducadas.
El cupo por hora va por horas de reloj: se renueva al empezar cada hora, no una hora después de la primera petición. Lo cambia quien tiene «Gestionar las claves de API», desde Opciones avanzadas al crear la clave o con Editar en su ficha.
Cuando se agota, la respuesta es 429 RATE_LIMIT_EXCEEDED con:
Retry-After: los segundos que faltan para la hora siguiente;X-RateLimit-Limit,X-RateLimit-RemainingyX-RateLimit-Reset, del cupo por hora de la clave.
En una respuesta correcta, esas tres cabeceras son las del freno de ráfagas, igual que en el resto de la API, no las de tu cupo por hora.
Si desde una misma dirección IP llegan 30 claves no válidas en un minuto, la API responde 429 a esa dirección sin mirar la clave hasta el minuto siguiente. Una integración sana no falla tanto: si te pasa, revisa que la clave esté bien copiada.
Saber lo que le queda
Lo que le queda a la clave esta hora lo dice la propia clave:
/api/v2/organization-api-keys/currentCon la clave en Authorization: Bearer. Devuelve, entre otros datos, rateLimitPerHour, rateLimitRemaining y rateLimitResetAt.
Esta consulta también cuenta como una petición. Si tu programa hace tandas grandes, consúltala al empezar cada tanda, no antes de cada petición. El resto de lo que devuelve está en Comprobar que funciona.
El uso de una clave
En la ficha de cada clave, en Ajustes, Claves de API, ves sus peticiones de las Últimas 24 horas, también hora a hora, y de los Últimos 7 días, y las rutas que ha usado. La pantalla lo pide con la sesión de una persona, no con la clave:
/api/v2/organization-api-keys/:id/usageUso de una clave. Con la sesión de una persona que tenga «Ver las claves de API» o «Gestionar las claves de API».
- last24hnumberobligatorio
- Peticiones de las últimas 24 horas.
- last7dnumberobligatorio
- Peticiones de los últimos 7 días.
- hourly{ hour, count }[]obligatorio
- Las últimas 24 horas, de la más antigua a la actual. hour es el inicio de cada hora, en UTC.
- routes{ method, path, count, lastAt }[]obligatorio
- Rutas usadas en los últimos 7 días, con los identificadores agrupados (:id) y la última vez que se llamó cada una.
Si una clave tiene uso que no reconoces, revócala y crea otra: cómo, en Revocar una clave.
La auditoría
Todo lo que hace una clave queda en el registro de auditoría a nombre de su persona responsable, con la marca «mediante la clave» y su nombre. Así sabes qué hizo cada programa sin perder de vista en nombre de quién lo hizo.
Crear, cambiar, renovar y revocar una clave también queda anotado, con quién lo hizo. Una revocación al dar de baja a la persona responsable deja su propia anotación por cada clave, con el motivo.
Siguiente paso
Ponlo en práctica
Lo encontrarás en Claves de API. Para abrirlo, entra con tu cuenta de UTILIA OS.