Límites de frecuencia y cuota

Cada clave tiene dos límites, compartidos por todos los equipos que lee: un límite de frecuencia, que fija a qué velocidad lee, y una cuota diaria, que fija cuánto lee. Los dos cuentan elementos, no peticiones. Un elemento es un objeto de una respuesta: una página del feed con 100 cambios son 100 elementos, eliminaciones incluidas.

Dos límites por clave

Qué peticiones cuentan para cada límite:

Cada endpoint de la referencia indica su fila: Sincronización para la primera y Lectura para la segunda.

Límite de frecuencia

Una clave lee hasta 2.000 elementos por minuto, con ráfagas de hasta 10.000. La capacidad que no usas se recupera a ese ritmo hasta completar de nuevo la ráfaga. Al superar el límite, la API responde 429 rate_limited, y Retry-After indica cuánto falta para que haya sitio para tu petición.

Cómo cuenta una petición:

• Antes de ejecutarse, una petición aparta su limit. Una petición de lista o del feed que no envía limit aparta 25; una petición de un solo registro aparta uno.
• Una vez ejecutada, se le cobran los elementos que devolvió, y como mínimo uno. Una página corta devuelve la diferencia, pero una petición que no devuelve nada cuesta igualmente un elemento: una búsqueda que no encuentra ningún lead, un identificador que responde 404 o cualquier otro error que reciba durante su ejecución, quota_exceeded incluido.
• Una petición rechazada antes de ejecutarse no se cobra, como una autenticación fallida, un permiso que falta o, en una ruta que usa Totem-Team, un equipo que la clave no puede leer o que aún no está listo. Una petición que indica un registro por su identificador, como GET /v1/leads/{id} o las actividades de un lead, comprueba su equipo durante la ejecución, así que un rechazo por ese equipo cuesta un elemento.
• A una petición de un solo registro se le cobra lo que devuelve: GET /v1/leads/{id} devuelve un lead con sus dos facetas, así que cuenta hasta tres elementos. Una búsqueda cuenta cada lead que devuelve, o uno si no encuentra ninguno.

Como una petición aparta primero su limit completo, un limit más pequeño te permite seguir leyendo cuando queda poca capacidad.

429 rate_limited también puede significar que tu dirección IP o tu clave están bloqueadas tras demasiados intentos de autenticación fallidos. Retry-After distingue los dos casos: un bloqueo siempre envía 600 segundos, la duración completa del bloqueo, mientras que el límite de frecuencia pide los pocos segundos que necesita tu petición. Ir más despacio no termina un bloqueo: busca el proceso de esa dirección que envía una clave ausente, mal formada, incorrecta o desconocida, corrígelo y espera. Autenticación explica qué cuenta como intento fallido.

Cuota diaria

Cada día UTC, una clave puede leer 250.000 elementos, o 3 veces el número de registros de sus equipos si es mayor. Para ese número cuentan los registros de todos los tipos, eliminaciones incluidas. Para la cuota cuenta cada elemento que devuelven las peticiones de la primera fila de la tabla, sea del tipo que sea.

El número de registros se toma con la primera petición de la clave de cada día UTC, así que un equipo que se añade a la clave más tarde ese día puede aumentar la cuota solo a partir del día siguiente. Planifica la carga inicial de un equipo grande para cuando su cuota lo permita.

La cuota deja margen para una carga inicial de todos los equipos y un día de consultas periódicas. Lo que la agota es volver a leer listas enteras una y otra vez.

Al agotar la cuota, esas peticiones responden 429 quota_exceeded hasta las 00:00 UTC, cuando la cuota se renueva. Retry-After indica los segundos que faltan. Las peticiones de un solo registro, la búsqueda y GET /v1/me siguen funcionando.

Reintenta tras un 429

Retry-After llega con cada 429 que devuelve la propia API, y siempre es un número entero de segundos. Espera al menos ese tiempo y vuelve a enviar la misma petición, con el mismo cursor. Mientras esperas no se pierde nada: el feed te guarda todos los cambios.

• Tras rate_limited, la espera suele ser de unos segundos, o de 600 segundos tras un bloqueo por intentos fallidos.
• Tras quota_exceeded, la espera dura hasta las 00:00 UTC y puede ser de horas. No dejes un proceso dormido tanto tiempo: termina la ejecución y programa la siguiente para esa hora. El cliente de referencia lo hace con su resultado retry_later.

Un 429 del cortafuegos que protege la API no trae Retry-After ni cuerpo de error JSON: reintenta con espera exponencial. Un 5xx tampoco lleva Retry-After: reinténtalo también con espera exponencial.

Estimación de la carga inicial

La tabla da el tiempo mínimo que el límite de frecuencia añade a una carga inicial, según los límites de esta página, para una sola clave sin más tráfico; durante la Beta es aproximado, como explica la nota del principio de esta página. Cuenta los registros de todos los tipos, un elemento cada uno: un lead con su atribución, su respuesta y tres actividades son seis registros. El tiempo de red, y el que Totem necesita para preparar un equipo recién añadido a una clave, se suman a esas cifras. Una copia que cabe en la ráfaga muestra Menos de 1 minuto: el límite de frecuencia no le añade nada, pero sigue llevando el tiempo de sus peticiones.

Buenas prácticas

• Sincroniza cada combinación de clave y equipo desde un solo proceso. Varios procesos con la misma clave comparten los mismos límites, así que solo consiguen hacerse esperar unos a otros.
• Pide páginas completas, de 100 elementos, durante una carga inicial.
• Consulta el feed de cambios cada 1 a 5 minutos. Una consulta que no encuentra nada nuevo cuesta un elemento del límite de frecuencia y nada de la cuota diaria.
• Lee los miembros y los servicios reservables al empezar con un equipo, cuando encuentres un identificador que no conoces y una vez al día: no en cada ejecución, ni otra vez por un identificador que la última lectura no resolvió.
• Nunca crees más integraciones ni claves para sortear los límites. Si se te quedan cortos, avísanos.