# 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.

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.000 por hora. Por defecto. Se cambia entre 10 y 10.000 al crearla o editarla.
- Ráfagas: 600 al minuto por ruta. Freno general de toda la API, contado por clave.
- Claves no válidas desde una dirección IP: 30 al 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-Remaining` y `X-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:

**`GET /api/v2/organization-api-keys/current`**

Con 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](https://os.utilia.ai/docs/developers/organization-api-keys/first-request#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:

**`GET /api/v2/organization-api-keys/:id/usage`**

Uso de una clave. Con la sesión de una persona que tenga «Ver las claves de API» o «Gestionar las claves de API».

Parámetro de ruta: `id`.

| Nombre | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `last24h` | `number` | Sí | Peticiones de las últimas 24 horas. |
| `last7d` | `number` | Sí | Peticiones de los últimos 7 días. |
| `hourly` | `{ hour, count }[]` | Sí | 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 }[]` | Sí | 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](https://os.utilia.ai/docs/developers/organization-api-keys/expiry-renewal-revocation#revocar-una-clave).

## La auditoría

Todo lo que hace una clave queda en el [registro de auditoría](https://os.utilia.ai/docs/guides/audit-log/overview) 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

- [Límites de uso y CORS](https://os.utilia.ai/docs/developers/getting-started/rate-limits-and-cors): Los límites generales de la API y desde qué webs se puede llamar.
- [Registro de auditoría](https://os.utilia.ai/docs/guides/audit-log/overview): Dónde se consulta lo que ha hecho cada persona y cada clave.