Telegram Bot API

Errores de la Telegram Bot API: qué significa cada uno y cómo solucionarlo

· 9 min de lectura

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"
}
CampoSignificado
okfalse en toda petición fallida.
error_codeEntero que replica el estado HTTP: 400, 401, 403, 404, 409, 413, 429, 5xx.
descriptionExplicación en texto plano, normalmente con el nombre del estado como prefijo: Bad Request:, Forbidden:, Conflict:.
parametersResponseParameters 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:

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ónCausaSolución
chat not foundchat_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_INVALIDEl 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 modifiedSe 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 foundPar 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 editedEl 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 emptyFalta 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 specifiedUn 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 invalidSe 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 chatEl 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 tecladocallback_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 inaccessibleSe 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

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ónQué pasóQué hacer
bot was blocked by the userEl 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 userEl 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 chatEl bot no está en el canal.Agrega el bot al canal como administrador con permiso para publicar.
bot was kicked from the group chatEl 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 deactivatedLa cuenta fue eliminada.Borra al usuario de tu lista de envíos.

409 Conflict en getUpdates

Errores 413, 429 y 5xx

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

  1. Registra el JSON completo de cada respuesta fallida: error_code, description y parameters.
  2. Verifica el token con getMe en Bot API Tester: un 401 significa que el problema es el token.
  3. Para chat not found y los errores 403, llama a getUpdates y compara el chat.id real con el de tu configuración.
  4. 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.

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.