Errores de la Telegram Bot API: qué significa cada uno y cómo solucionarlo
Los errores de la Telegram Bot API llegan como JSON con "ok": false, un error_code numérico como 400, 403 o 429 y una description legible del tipo Bad Request: chat not found. Casi todos tienen una de una docena de causas conocidas: un chat id incorrecto, un usuario que bloqueó al bot, una segunda instancia del bot o demasiados mensajes por segundo. Aquí tienes el formato de la respuesta, una tabla de los errores más comunes con su solución, agrupados por código, y código listo para copiar en Python y JavaScript que respeta retry_after y migrate_to_chat_id.
Formato de la respuesta de error
Toda respuesta de la Bot API es un objeto JSON con un campo booleano ok. Si todo sale bien, los datos están en result; si falla, recibes esto:
{
"ok": false,
"error_code": 400,
"description": "Bad Request: chat not found"
}
| Campo | Significado |
|---|---|
ok | false en toda petición fallida. |
error_code | Entero que replica el estado HTTP: 400, 401, 403, 404, 409, 413, 429, 5xx. |
description | Explicación en texto plano, normalmente con el nombre del estado como prefijo: Bad Request:, Forbidden:, Conflict:. |
parameters | ResponseParameters opcional que ayuda a manejar el error de forma automática: retry_after (segundos de espera tras el control de flood) y migrate_to_chat_id (el nuevo id de un grupo que pasó a ser supergrupo). |
Dos respuestas con parameters que conviene manejar en el código:
{"ok": false, "error_code": 429, "description": "Too Many Requests: retry after 35", "parameters": {"retry_after": 35}}
{"ok": false, "error_code": 400, "description": "Bad Request: group chat was upgraded to a supergroup chat", "parameters": {"migrate_to_chat_id": -1001234567890}}
No bases tu lógica en el texto de description
Telegram no publica una lista completa de los mensajes de error de la Bot API. Las descripciones de esta guía son los textos que la API devuelve hoy, pero son texto plano para personas y pueden cambiar sin aviso. La documentación oficial incluso dice que el contenido de error_code puede cambiar. Por eso, un bot robusto:
- decide primero según
error_code(400, 403, 429, 5xx); - usa
parameters.retry_afteryparameters.migrate_to_chat_idsiempre que estén presentes, en vez de sacar números de la descripción; - busca subcadenas en la descripción solo cuando debe distinguir errores con el mismo código, sin distinguir mayúsculas y con una alternativa segura si nada coincide;
- registra la descripción completa en los logs, para que los mensajes nuevos aparezcan ahí en lugar de perderse.
400 Bad Request: errores comunes de Telegram
Un error 400 Bad Request de Telegram significa que la petición llegó a la API, pero algo en ella está mal: un parámetro, el chat de destino o el estado del mensaje.
| Descripción | Causa | Solución |
|---|---|---|
chat not found | chat_id incorrecto, id de grupo sin -100, un usuario que nunca inició el bot, un bot que no está en el grupo o canal, o un id de producción usado en el servidor de prueba. | Escríbele al bot (o agrégalo al chat) y copia el id de getUpdates; consulta la guía del chat id. |
PEER_ID_INVALID | El id está mal formado o apunta a un chat con el que el bot nunca interactuó. | Igual que con chat not found: toma un id nuevo de una actualización. |
message is not modified | Se llamó a un método de edición con exactamente el mismo texto y teclado que ya tiene el mensaje. Es típico cuando el usuario presiona el mismo botón dos veces. | Compara antes de editar, o captura e ignora este error. |
message to edit not found | Par message_id/chat_id incorrecto, o el mensaje se borró. | Guarda el message_id que devuelve el método de envío junto con su chat id. |
message can't be edited | El mensaje no lo envió el bot, o ya no se puede editar. | Envía un mensaje nuevo en lugar de editar. |
can't parse entities: … | Marcado de parse_mode roto: un < o & sin escapar en HTML, o alguno de _ * [ ] ( ) ~ ` > # + - = | { } . ! sin escapar en MarkdownV2. El texto después de los dos puntos indica el desplazamiento en bytes. | Escapa el texto que viene del usuario o envíalo sin parse_mode. |
message text is empty | Falta text o está vacío; muchas veces es un cuerpo JSON enviado sin Content-Type: application/json. | Revisa el valor y la codificación de la petición. |
wrong file identifier/HTTP URL specified | Un file_id de otro bot (los file ids están ligados a un solo bot), o una URL que Telegram no puede descargar o que supera los límites de envío por URL (5 MB para fotos, 20 MB para otros archivos). | Vuelve a subir el archivo como multipart/form-data o usa un enlace directo público. |
query is too old and response timeout expired or query ID is invalid | Se llamó a answerCallbackQuery o answerInlineQuery demasiado tarde, dos veces o con un id incorrecto. | Responde al inicio del handler, antes del trabajo lento; después de un reinicio, ignora los callback queries viejos. |
not enough rights to send text messages to the chat (fotos, documentos…) | El bot tiene restricciones en el grupo o no tiene permiso para publicar en el canal. | Dale al bot el permiso necesario o derechos de administrador. |
group chat was upgraded to a supergroup chat | El grupo básico pasó a ser supergrupo y recibió un id nuevo, que llega en parameters.migrate_to_chat_id. | Guarda el id nuevo y repite la petición con él. |
BUTTON_DATA_INVALID y otros errores del teclado | callback_data fuera del rango de 1–64 bytes (los caracteres no latinos ocupan 2–4 bytes cada uno), o un reply_markup mal formado. | Guarda los datos largos en tu servidor y pon una clave corta en callback_data. |
member list is inaccessible | Se llamó a un método relacionado con miembros donde el bot no puede leer la lista, normalmente un canal en el que no es administrador. | Haz al bot administrador o no consultes miembros ahí. |
Para reproducir un error sin riesgo, abre sendMessage en Bot API Tester, escribe un chat_id inventado y mira la respuesta JSON cruda.
401 Unauthorized y 404 Not Found
401 Unauthorized: el token es incorrecto o fue revocado. También pasa cuando se envía un token de producción al servidor de prueba o al revés. Verifica el token congetMe; si se filtró y lo revocaste, toma el nuevo en @BotFather.404 Not Found: la URL no coincide conhttps://api.telegram.org/bot<token>/METHOD_NAME. Causas típicas: falta el prefijobotantes del token, el token tiene espacios o saltos de línea, o el nombre del método está mal escrito. Los nombres de métodos no distinguen mayúsculas, así quesendmessagefunciona, perosendMesageno.
403 Forbidden: bot was blocked by the user y errores similares
El error 403 significa que el bot no tiene permitido escribir en ese chat. Reintentar no sirve; lo que hay que hacer es actualizar tus datos.
| Descripción | Qué pasó | Qué hacer |
|---|---|---|
bot was blocked by the user | El usuario bloqueó o detuvo el bot. | Marca al usuario como inactivo y deja de escribirle. En chats privados el bot también recibe una actualización my_chat_member cuando lo bloquean o desbloquean. |
bot can't initiate conversation with a user | El usuario nunca abrió el bot. Los bots no pueden escribir primero. | Pide al usuario que presione Iniciar, por ejemplo con un enlace t.me/your_bot. |
bot is not a member of the channel chat | El bot no está en el canal. | Agrega el bot al canal como administrador con permiso para publicar. |
bot was kicked from the group chat | El bot fue expulsado del grupo (la variante de supergrupo menciona supergroup chat). | Quita el chat de tu lista o pide a un administrador que vuelva a agregar el bot. |
user is deactivated | La cuenta fue eliminada. | Borra al usuario de tu lista de envíos. |
409 Conflict en getUpdates
Conflict: terminated by other getUpdates request; make sure that only one bot instance is running: dos procesos hacen polling con el mismo token, por ejemplo una terminal olvidada, un segundo contenedor o un deploy que arrancó antes de que se detuviera el anterior. Deja exactamente un proceso de polling por token.Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first: el bot tiene un webhook y getUpdates no funciona mientras exista. Llama adeleteWebhook, o conserva el webhook y deja de hacer polling.
Errores 413, 429 y 5xx
413 Request Entity Too Large: el archivo es más grande de lo que acepta la API. Los bots pueden subir hasta 50 MB a través deapi.telegram.org; un servidor local de Bot API sube ese límite a 2000 MB.429 Too Many Requests: retry after N: control de flood. Esperaparameters.retry_aftersegundos y repite. Luego baja el ritmo: alrededor de 1 mensaje por segundo por chat, 20 por minuto en un grupo y unos 30 por segundo en total. Las cifras y las estrategias de colas están en la guía de límites.500,502 Bad Gatewayy otros 5xx: un problema del lado de Telegram o en el camino hacia él. Reintenta con backoff exponencial. El cuerpo de un 502 puede ser una página que no es JSON, así que no supongas queresponse.json()siempre funciona.
Código para manejar errores con retry_after y migrate_to_chat_id
Este wrapper reintenta los 429 después de retry_after, sigue migrate_to_chat_id, aplica backoff en los 5xx y en errores de red, y lanza un error tipado para todo lo demás, así quien llama decide qué hacer. Python usa requests; la versión de JavaScript necesita Node.js 18+ y se ejecuta como archivo .mjs.
import os
import time
import requests
TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
class TelegramError(Exception):
def __init__(self, method, code, description, parameters=None):
super().__init__(f"{method}: {code} {description}")
self.code = code
self.description = description
self.parameters = parameters or {}
def call(method, max_retries=5, **params):
for attempt in range(max_retries):
try:
data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
except (requests.RequestException, ValueError):
# error de red o respuesta que no es JSON (p. ej. una página HTML de 502)
time.sleep(2 ** attempt)
continue
if data.get("ok"):
return data["result"]
code = data.get("error_code")
extra = data.get("parameters") or {}
if "retry_after" in extra: # 429, control de flood: espera lo indicado
time.sleep(extra["retry_after"])
continue
if "migrate_to_chat_id" in extra and "chat_id" in params:
print(f"el chat {params['chat_id']} migró a {extra['migrate_to_chat_id']}: actualiza tu base de datos")
params["chat_id"] = extra["migrate_to_chat_id"]
continue
if code is not None and code >= 500: # problema del lado de Telegram: espera más
time.sleep(2 ** attempt)
continue
raise TelegramError(method, code, data.get("description", ""), extra)
raise TelegramError(method, None, "se agotaron los reintentos")
def notify(chat_id, text):
try:
return call("sendMessage", chat_id=chat_id, text=text)
except TelegramError as e:
if e.code == 403:
# bloqueado, expulsado o cuenta eliminada: deja de escribir a este chat
print(f"el chat {chat_id} no es accesible: {e.description}")
elif e.code == 400 and "chat not found" in e.description.lower():
print(f"chat id incorrecto: {chat_id}")
else:
raise
notify(123456789, "¡Hola!")const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
const sleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));
class TelegramError extends Error {
constructor(method, code, description, parameters = {}) {
super(`${method}: ${code} ${description}`);
this.code = code;
this.description = description;
this.parameters = parameters;
}
}
async function call(method, params = {}, maxRetries = 5) {
params = { ...params };
for (let attempt = 0; attempt < maxRetries; attempt++) {
let data;
try {
const res = await fetch(`${API}/${method}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(params),
signal: AbortSignal.timeout(40_000),
});
data = await res.json();
} catch {
// error de red o respuesta que no es JSON (p. ej. una página HTML de 502)
await sleep(2 ** attempt);
continue;
}
if (data.ok) return data.result;
const code = data.error_code;
const extra = data.parameters ?? {};
if (extra.retry_after !== undefined) { // 429, control de flood: espera lo indicado
await sleep(extra.retry_after);
continue;
}
if (extra.migrate_to_chat_id !== undefined && "chat_id" in params) {
console.log(`el chat ${params.chat_id} migró a ${extra.migrate_to_chat_id}: actualiza tu base de datos`);
params.chat_id = extra.migrate_to_chat_id;
continue;
}
if (code >= 500) { // problema del lado de Telegram: espera más
await sleep(2 ** attempt);
continue;
}
throw new TelegramError(method, code, data.description ?? "", extra);
}
throw new TelegramError(method, null, "se agotaron los reintentos");
}
async function notify(chatId, text) {
try {
return await call("sendMessage", { chat_id: chatId, text });
} catch (err) {
if (!(err instanceof TelegramError)) throw err;
if (err.code === 403) {
// bloqueado, expulsado o cuenta eliminada: deja de escribir a este chat
console.log(`el chat ${chatId} no es accesible: ${err.description}`);
} else if (err.code === 400 && err.description.toLowerCase().includes("chat not found")) {
console.log(`chat id incorrecto: ${chatId}`);
} else {
throw err;
}
}
}
await notify(123456789, "¡Hola!");Una advertencia: una petición que expiró de tu lado puede haberse procesado de todos modos, así que reintentar un envío después de un error de red puede, en ocasiones, entregar el mensaje dos veces.
Checklist de depuración
- Registra el JSON completo de cada respuesta fallida:
error_code,descriptionyparameters. - Verifica el token con getMe en Bot API Tester: un 401 significa que el problema es el token.
- Para
chat not foundy los errores 403, llama agetUpdatesy compara elchat.idreal con el de tu configuración. - Para el 409, busca una segunda instancia en ejecución y revisa
getWebhookInfo.
Guías relacionadas: cómo obtener el chat id de Telegram, enviar mensajes y escapar el texto según parse_mode, límites de la Telegram Bot API y manejo del 429 y configurar un webhook.
Preguntas frecuentes
¿Qué significa «Bad Request: chat not found» en Telegram?
El bot no puede ver el chat que corresponde a tu chat_id: el id es incorrecto o le falta el prefijo -100, el usuario nunca inició el bot o el bot no es miembro del grupo o canal. Escríbele primero al bot y toma el id de getUpdates.
¿Cómo manejo «Forbidden: bot was blocked by the user»?
No se puede arreglar desde el bot: el usuario lo bloqueó. Captura el código de error 403, marca al usuario como inactivo en tu base de datos y deja de enviarle mensajes hasta que vuelva a escribirle al bot.
¿Por qué getUpdates devuelve 409 Conflict?
O hay otro proceso haciendo polling con el mismo token (terminated by other getUpdates request) o hay un webhook configurado (can't use getUpdates method while webhook is active). Detén la segunda instancia o llama a deleteWebhook.
¿Cuánto debo esperar después de 429 Too Many Requests?
Exactamente lo que indica parameters.retry_after, en segundos, y luego repite la petición. No reintentes de inmediato ni uses una pausa fija en el código: el valor cambia de una respuesta a otra.
¿Mi código debe revisar el texto de description?
Lo menos posible. La descripción es un texto para personas que Telegram puede cambiar. Decide primero según error_code y parameters, y busca subcadenas en la descripción, sin distinguir mayúsculas, solo cuando necesites diferenciar dos errores con el mismo código.
¿Qué significa 401 Unauthorized en la Bot API?
El token no es válido: lo escribiste mal, se revocó en @BotFather o pertenece al otro entorno (producción o servidor de prueba). Verifícalo con getMe y obtén el token actual en /mybots → API Token.
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.
Límites de la Telegram Bot API: rate limit, error 429, tamaño de archivos y de mensajes
Límites de la Telegram Bot API: 30 msg/s, 1 msg/s por chat, 20/min en grupos, cómo manejar 429 con retry_after y límites de tamaño de archivo y de texto.
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.