Límites de la Telegram Bot API: rate limit, error 429, tamaño de archivos y de mensajes
Los límites de la Telegram Bot API parecen sencillos en papel: alrededor de 1 mensaje por segundo en un mismo chat, 20 mensajes por minuto en un grupo y unos 30 mensajes por segundo sumando todos los chats. Si los superas, la API responde 429 Too Many Requests con un valor retry_after. Esta página reúne todos los límites de la Telegram Bot API (ritmo de envío, envíos pagados, tamaño de archivos, longitud de textos y actualizaciones) con código que mantiene a tu bot dentro de ellos.
Rate limit de la Telegram Bot API para enviar mensajes
El Bots FAQ oficial indica estos límites para el envío normal y gratuito:
| Alcance | Límite | Notas |
|---|---|---|
| Un chat | ≈ 1 mensaje por segundo | Se toleran ráfagas cortas; después empiezan los errores 429. |
| Un grupo | 20 mensajes por minuto | Se cuenta por cada chat de grupo. |
| Envíos masivos | ≈ 30 mensajes por segundo | Hasta 1000 por segundo con envíos pagados. |
Toma estas cifras como referencia, no como contrato. Telegram advierte que los límites pueden cambiar, y en el entorno de prueba los límites de flood no son más altos (incluso pueden ser más estrictos). Un código que respeta retry_after sobrevive a cambios que romperían un "30" escrito a mano.
429 Too Many Requests y retry_after
Cuando alcanzas un límite de flood, la respuesta se ve así:
{
"ok": false,
"error_code": 429,
"description": "Too Many Requests: retry after 17",
"parameters": {"retry_after": 17}
}
retry_after es la cantidad de segundos que faltan para poder repetir la petición. Espera al menos ese tiempo y envía la misma petición otra vez; reintentar de inmediato solo alarga el bloqueo. Una función auxiliar en Python o JavaScript:
import time
import requests
API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"
def call(method, max_attempts=5, **params):
for _ in range(max_attempts):
r = requests.post(f"{API}/{method}", json=params, timeout=30).json()
if r["ok"]:
return r["result"]
if r["error_code"] != 429:
raise RuntimeError(f'{r["error_code"]}: {r["description"]}')
time.sleep(r.get("parameters", {}).get("retry_after", 1) + 0.5)
raise RuntimeError("sigue limitado, me rindo")
call("sendMessage", chat_id=123456789, text="Hola")const API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function call(method, params, maxAttempts = 5) {
for (let i = 0; i < maxAttempts; i++) {
const res = await fetch(`${API}/${method}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(params),
});
const data = await res.json();
if (data.ok) return data.result;
if (data.error_code !== 429) throw new Error(data.description);
await sleep(((data.parameters?.retry_after ?? 1) + 0.5) * 1000);
}
throw new Error("sigue limitado");
}Regula los envíos masivos con una cola
Los reintentos resuelven peticiones sueltas. Para boletines y notificaciones tienes que regular el envío en sí, por ejemplo con un ritmo global un poco por debajo de 30 mensajes por segundo:
def broadcast(chat_ids, text, per_second=25):
for chat_id in chat_ids:
try:
call("sendMessage", chat_id=chat_id, text=text)
except RuntimeError as e:
print(chat_id, e) # 403: el usuario bloqueó al bot, sácalo de la lista
time.sleep(1 / per_second)async function broadcast(chatIds, text, perSecond = 25) {
for (const chatId of chatIds) {
try {
await call("sendMessage", { chat_id: chatId, text });
} catch (e) {
console.log(chatId, e.message); // 403: el usuario bloqueó al bot, sácalo de la lista
}
await sleep(1000 / perSecond);
}
}En producción, ejecuta esto en un worker en segundo plano, guarda una marca de tiempo por chat para que ninguno reciba más de un mensaje por segundo y elimina los chats que devuelven 403 en lugar de reintentarlos. Sin envíos pagados, Telegram recomienda repartir los envíos grandes en intervalos más largos, por ejemplo de 8 a 12 horas.
Envíos pagados: hasta 1000 mensajes por segundo
Si 30 mensajes por segundo no te alcanzan, activa los envíos pagados (paid broadcasts) en @BotFather y pasa "allow_paid_broadcast": true a métodos de envío como sendMessage, sendPhoto o sendMediaGroup. Así el bot puede enviar hasta 1000 mensajes por segundo. Cada mensaje por encima de los 30 gratuitos por segundo cuesta 0,1 Telegram Stars del saldo del bot, y solo se cobran los mensajes enviados con éxito. Para usarlo se necesita un saldo mínimo de Stars (el Bots FAQ también menciona un umbral de audiencia), así que revisa las cifras actuales en la documentación oficial antes de planear con esto.
Límites de tamaño de archivo de los bots de Telegram
| Operación | Límite |
|---|---|
Subir un archivo con multipart/form-data | 50 MB |
| Subir una foto | 10 MB; ancho + alto ≤ 10000, relación de aspecto ≤ 20 |
| Enviar una foto por URL HTTP | 5 MB |
| Enviar otros archivos por URL HTTP | 20 MB (sendDocument por URL solo funciona con .PDF y .ZIP) |
Descargar con getFile | 20 MB; el enlace de descarga es válido al menos 1 hora |
Reenviar por file_id | Sin límite de tamaño |
Un servidor local de Bot API elimina las dos restricciones más grandes: subidas de hasta 2000 MB y descargas sin límite de tamaño, además de webhooks por HTTP plano en cualquier puerto. Llama a logOut antes de apuntar el bot a tu propio servidor. Para revisar un archivo antes de descargarlo, llama a getFile en Bot API Tester y mira file_size y file_path.
Longitud de mensajes y otros límites de contenido
| Elemento | Límite |
|---|---|
| Texto del mensaje | 1–4096 caracteres después de procesar las entidades |
| Descripción (caption) de multimedia | 0–1024 caracteres |
Rich message (sendRichMessage) | 32768 caracteres UTF-8, 500 bloques, 50 archivos multimedia, 20 columnas de tabla |
callback_data | 1–64 bytes |
| Grupo de medios (media group) | 2–10 elementos |
| Respuesta a una consulta inline | Hasta 50 resultados |
Texto de answerCallbackQuery | 0–200 caracteres |
setMyCommands | 100 comandos; comando de 1–32 caracteres, descripción de 1–256 |
Parámetro start del deep link | Hasta 64 caracteres: A-Z a-z 0-9 _ - |
sendData de Mini App | Hasta 4096 bytes |
callback_data se cuenta en bytes, y los caracteres fuera de ASCII (como á, ñ o los emojis) ocupan de 2 a 4 bytes en UTF-8, así que guarda un id corto en el botón y deja los detalles en tu base de datos. Los textos de más de 4096 caracteres deben dividirse, de preferencia en los saltos de línea:
def split_text(text, limit=4000): # un poco menos de 4096 por seguridad
parts, current = [], ""
for line in text.splitlines(keepends=True):
if current and len(current) + len(line) > limit:
parts.append(current)
current = ""
while len(line) > limit:
parts.append(line[:limit])
line = line[limit:]
current += line
if current:
parts.append(current)
return partsfunction splitText(text, limit = 4000) { // un poco menos de 4096 por seguridad
const parts = [];
let current = "";
for (let line of text.split(/(?<=\n)/)) { // divide en líneas, conserva "\n"
if (current && current.length + line.length > limit) {
parts.push(current);
current = "";
}
while (line.length > limit) {
parts.push(line.slice(0, limit));
line = line.slice(limit);
}
current += line;
}
if (current) parts.push(current);
return parts;
}Límites de actualizaciones y del webhook
- Las actualizaciones entrantes se guardan en los servidores de Telegram hasta 24 horas, mientras tu bot no las reciba.
getUpdatesdevuelve 1–100 actualizaciones por llamada (limit, 100 por defecto). Usatimeoutpara long polling y confirma las actualizaciones conoffset= últimoupdate_id+ 1.getUpdatesno funciona mientras haya un webhook configurado (409 Conflict) hasta que llames adeleteWebhook.setWebhookaceptamax_connectionsde 1 a 100 (40 por defecto) y solo los puertos 443, 80, 88 y 8443. Un servidor local de Bot API permite hasta 100000 conexiones y cualquier puerto.
Cómo mantenerte dentro de los límites de la Telegram Bot API
- Envía todo a través de una sola cola con un ritmo global menor a 30 por segundo y como máximo un mensaje por segundo por chat.
- Muestra el progreso editando un solo mensaje con
editMessageTexten lugar de publicar muchos nuevos. - Reenvía multimedia por
file_iden vez de volver a subirla. - Respeta
retry_aftery nunca reintentes los errores 403. - Pasa
allowed_updatespara recibir solo los tipos de actualización que realmente procesas.
Guías relacionadas: enviar mensajes con la Bot API trata el formato y los errores de cada mensaje, configurar un webhook explica cómo recibir actualizaciones a gran escala y las novedades de Bot API 10 presenta los rich messages y sus límites.
Preguntas frecuentes
¿Cuál es el rate limit de la Telegram Bot API?
El Bots FAQ de Telegram da tres cifras: evita más de 1 mensaje por segundo en un mismo chat, no envíes más de 20 mensajes por minuto en un grupo y unos 30 mensajes por segundo para envíos masivos. Si los superas, recibes 429 Too Many Requests.
¿Cómo soluciono 429 Too Many Requests en Telegram?
Lee parameters.retry_after del error, espera esa cantidad de segundos y repite la misma petición. Para no volver a chocar con el límite, envía a través de una cola que regule el ritmo por chat y en total.
¿Cuál es el límite de tamaño de archivo de un bot de Telegram?
Los bots pueden subir archivos de hasta 50 MB (fotos de hasta 10 MB) y descargar archivos de hasta 20 MB con getFile. El envío por URL está limitado a 5 MB para fotos y 20 MB para otros archivos. Un servidor local de Bot API permite subir hasta 2000 MB y descargar sin límite de tamaño.
¿Qué tan largo puede ser un mensaje de un bot de Telegram?
Un mensaje de texto admite 1–4096 caracteres después de procesar las entidades y la descripción de un archivo multimedia, 0–1024 caracteres, así que los textos más largos hay que dividirlos. Los rich messages (Bot API 10.1+) permiten hasta 32768 caracteres UTF-8.
¿Cómo puede un bot de Telegram enviar más de 30 mensajes por segundo?
Activa los envíos pagados en @BotFather y pasa allow_paid_broadcast: true. El bot podrá enviar hasta 1000 mensajes por segundo; cada mensaje por encima de los 30 gratuitos por segundo cuesta 0,1 Telegram Stars y solo se cobran los envíos exitosos.
¿Cuánto tiempo guarda Telegram las actualizaciones de un bot?
Las actualizaciones no entregadas se guardan hasta 24 horas. getUpdates devuelve como máximo 100 actualizaciones por llamada; confírmalas pasando offset igual al último update_id + 1.
Guías relacionadas
Cómo crear un bot en Telegram paso a paso: de BotFather a tu primer mensaje
Aprende a crear un bot de Telegram: /newbot en @BotFather, token, prueba con getMe y tu primer mensaje con curl y Python. Gratis y sin servidor.
Cómo desplegar un bot de Telegram: VPS, Docker y hosting serverless
Cómo desplegar un bot de Telegram: polling o webhook, servicio systemd en un VPS, Docker, Cloudflare Workers con secret_token y checklist de lanzamiento.
Telegram Bot API 10.0–10.5: ajustes del bot, widgets, rich messages, mensajes efímeros, modo invitado y más
Qué hay de nuevo en Telegram Bot API 10.0–10.5: setMySettings y BotFullInfo, widgets HTML, mensajes rich y efímeros, modo invitado, con ejemplos JSON.
Errores de la Telegram Bot API: qué significa cada uno y cómo solucionarlo
Errores de la Telegram Bot API: 400 chat not found, 403 bot was blocked by the user, 409 Conflict y 429 retry_after. Causas, soluciones y código de manejo.
Comandos de un bot de Telegram: setMyCommands, scopes y deep links con /start
Configura los comandos de tu bot de Telegram: /setcommands en @BotFather, setMyCommands con scopes e idiomas, parámetro de /start y /cmd@bot en grupos.
Teclados de bots de Telegram: teclado inline, botones callback y reply keyboard
Agrega botones a tu bot de Telegram: teclado inline con callback_data, answerCallbackQuery, editar el mensaje tras cada clic, reply keyboard y ForceReply.
Integración de n8n con Telegram: conecta tu bot, dispara flujos y envía mensajes
Integra n8n con Telegram: token del bot como Access Token, webhook del Telegram Trigger por HTTPS, envío de mensajes por chat id y errores comunes.
Cómo enviar mensajes con la API de Telegram: sendMessage paso a paso
Envía mensajes con la Bot API de Telegram: sendMessage con curl, Python y JavaScript, formato HTML y MarkdownV2, botones inline y errores 400, 403 y 429.
Cómo obtener el token de un bot de Telegram (y qué hacer si se filtra)
Cómo obtener el token de tu bot de Telegram con @BotFather, encontrarlo si el bot ya existe, comprobarlo con getMe y revocarlo si se filtró.
Webhook de Telegram: cómo configurar setWebhook para tu bot (Python y n8n)
Configura el webhook de tu bot de Telegram: requisitos HTTPS, setWebhook con secret_token, getWebhookInfo, handler en Python y errores típicos en n8n.
Cómo obtener el chat id de Telegram: usuarios, grupos, canales y temas
Obtén el chat id de Telegram para tu bot con getUpdates: usuarios, grupos, supergrupos (-100…), canales y temas, y qué hacer si result viene vacío.
Bot inline de Telegram: cómo activar el modo inline y responder consultas
Crea un bot inline de Telegram: activa el modo inline con @BotFather o setMySettings, procesa inline_query y responde con answerInlineQuery.
Pagos con Telegram Stars en bots: facturas, pre-checkout, reembolsos y suscripciones
Acepta pagos con Telegram Stars en tu bot: sendInvoice con XTR, pre_checkout_query, successful_payment, reembolsos y suscripciones, con código.
Servidor de pruebas de Telegram: cómo probar un bot en el entorno de pruebas
Usa el servidor de pruebas de Telegram: entra al entorno de pruebas, crea un bot de prueba, llama a la Bot API con /test/ y activa TEST en nuestro tester.
Widgets de Telegram para tu sitio web: iniciar sesión con Telegram, posts, comentarios y botón compartir
Integra Telegram en tu sitio: iniciar sesión con Telegram (OIDC), el Login Widget clásico con verificación del hash, posts embebidos y botón compartir.
API JavaScript de TelegramWidget: referencia, eventos, errores y límites
Referencia de la API JavaScript TelegramWidget: propiedades, request(), eventos, errores, variables CSS, widget_query, answerWidgetQuery y límites.
Ejemplos de widgets de Telegram: HTML completo y bot en Python
Ejemplos de widgets de Telegram listos para usar: tarjeta de pedido, contador con widget_query, encuesta compartida en vivo y vista previa en el navegador.
Widgets de Telegram: HTML interactivo dentro de los mensajes de tu bot
Widgets de Telegram (Bot API 10.4): qué son, cómo funcionan sendWidget, chat_data y public_data, dónde se usan hoy y en qué difieren de las Mini Apps.
Cómo probar una Mini App de Telegram: del navegador a Telegram real
Cómo probar una Mini App de Telegram: modo mock en el navegador, localhost con túnel HTTPS, entorno de prueba, DevTools y validación de initData.