Límites de tasa

Los límites de tasa se aplican por endpoint sobre una ventana móvil de 60 segundos. Cada endpoint tiene su propio contador, así que alcanzar el límite en una ruta nunca afecta a otra. Superar un límite devuelve 429 Too Many Requests.

Cómo funciona

• La ventana es de 1 minuto para cada endpoint.
• Los límites están aislados por endpoint — list-boards y send-message se cuentan por separado.
• Cada respuesta lleva encabezados de límite de tasa para que puedas regular tu ritmo antes de alcanzar el tope.

Encabezados de respuesta

Encabezado	Descripción
X-RateLimit-Limit	Máximo de solicitudes permitidas para este endpoint por ventana.
X-RateLimit-Remaining	Solicitudes restantes en la ventana actual.
X-RateLimit-Reset	Cuándo se reinicia la ventana actual.
Retry-After	Segundos a esperar antes de reintentar (se envía solo en 429).

Límites por categoría

Los límites se agrupan en unos pocos niveles. El tope exacto depende de qué tan pesada sea la operación.

Categoría	Límite típico (por minuto)	Ejemplos
Lecturas	50	List boards, get a row, list channels, list notifications, list bookings
Lecturas más pesadas	30	Docs tree, drive tree, todas las lecturas de /workspace/*
Escrituras	30	Crear/actualizar/eliminar filas, docs, comentarios, carpetas; upload presigned URLs
Escrituras pesadas	20	Escrituras de markdown (row, column, doc), inicio/finalización de subida multipart
Búsqueda	60	El endpoint /search multientidad (docs/drive search son 50)
Mutaciones de notificaciones	60	Marcar leída/no leída, eliminar
Mensajería	100	Send channel message, send direct message
Exportación	10	Exportación asíncrona de tabla (el endpoint más restringido)

Límites representativos por endpoint

Endpoint	Método	Límite / min
/board/list-boards	GET	50
/board/{boardId}/table/{tableId}/rows	GET	50
/board/{boardId}/table/{tableId}/row	POST	30
/board/{boardId}/table/{tableId}/row/{rowId}/md	POST	20
/board/{boardId}/table/{tableId}/export	POST	10
/docs/tree	GET	30
/docs/{docId}/md	POST	20
/drive/files/upload/multipart/start	POST	20
/search	GET	60
/notifications	GET	50
/notifications/{notificationId}	PATCH / DELETE	60
/workspace/info	GET	30
/chat/channels	GET	50
/chat/channel/{channelId}/send-message	POST	100

nota

Estos números son precisos al momento de escribir, pero pueden cambiar. Lee siempre los encabezados X-RateLimit-* en tiempo de ejecución en lugar de codificar límites de forma fija — y consulta la referencia de la API para conocer el valor actual de un endpoint específico.

La respuesta 429

Cuando superas un límite, el endpoint devuelve:

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many requests, please try again later",
  "retryAfter": 27
}

El encabezado Retry-After lleva el mismo valor (en segundos) que el campo retryAfter del cuerpo — el tiempo hasta que se reinicia la ventana.

Orientación sobre backoff

• Respeta Retry-After. Ante un 429, espera el número de segundos que indica antes de reintentar.
• Usa backoff exponencial como respaldo. Si no hay Retry-After presente (por ejemplo en un 5xx), aplica backoff exponencial: 1s, 2s, 4s, …
• Vigila X-RateLimit-Remaining. Ralentiza proactivamente a medida que se acerca a cero en lugar de esperar a un 429.
• Distribuye el trabajo masivo. Al iterar listas grandes o crear filas en lote, agrega un pequeño retraso entre llamadas para mantenerte por debajo del tope por minuto.
• Limita los reintentos. Ríndete tras unos pocos intentos y expón el error en lugar de reintentar indefinidamente.

Consulta Manejo de errores para ver un ejemplo completo de reintentos.