Telegram Bot API

Erros do Telegram Bot API: o que cada erro significa e como resolver

· 9 min de leitura

Os erros do Telegram Bot API voltam como JSON com "ok": false, um error_code numérico como 400, 403 ou 429 e uma description legível, como Bad Request: chat not found. Quase todos têm uma de umas doze causas conhecidas: chat id errado, usuário que bloqueou o bot, uma segunda instância do bot ou mensagens demais por segundo. Abaixo estão o formato da resposta, uma tabela com os erros mais comuns e suas soluções, agrupados por código, e um código de tratamento em Python e JavaScript, pronto para copiar, que respeita retry_after e migrate_to_chat_id.

Formato da resposta de erro

Toda resposta do Bot API é um objeto JSON com um ok booleano. Quando dá certo, os dados vêm em result; quando falha, você recebe isto:

{
  "ok": false,
  "error_code": 400,
  "description": "Bad Request: chat not found"
}
CampoSignificado
okfalse em toda requisição que falhou.
error_codeInteiro, espelha o status HTTP: 400, 401, 403, 404, 409, 413, 429, 5xx.
descriptionExplicação em texto puro, geralmente com o nome do status na frente: Bad Request:, Forbidden:, Conflict:.
parametersResponseParameters opcionais que ajudam a tratar o erro automaticamente: retry_after (segundos de espera após o flood control) e migrate_to_chat_id (o novo id de um grupo que virou supergrupo).

Duas respostas com parameters que você deve tratar no 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}}

Não baseie a lógica no texto da descrição

O Telegram não publica uma lista completa das mensagens de erro do Bot API. As descrições deste guia são os textos que a API devolve hoje, mas são texto puro para humanos e podem mudar sem aviso. A documentação oficial diz até que o conteúdo de error_code está sujeito a mudanças. Por isso, um bot robusto:

400 Bad Request: erros comuns do Telegram

O erro 400 Bad Request do Telegram significa que a requisição chegou à API, mas algo nela está errado: um parâmetro, o chat de destino ou o estado da mensagem.

DescriçãoCausaSolução
chat not foundchat_id errado, id de grupo sem -100, usuário que nunca iniciou o bot, bot fora do grupo ou canal, ou id de produção usado no servidor de testes.Mande uma mensagem ao bot (ou adicione-o ao chat) e copie o id do getUpdates; veja o guia de chat id.
PEER_ID_INVALIDO id está malformado ou aponta para um chat com o qual o bot nunca interagiu.Igual a chat not found: pegue um id novo de um update.
message is not modifiedUm método de edição foi chamado com exatamente o mesmo texto e reply markup que a mensagem já tem. Comum quando o usuário toca duas vezes no mesmo botão.Compare antes de editar, ou capture e ignore esse erro.
message to edit not foundPar message_id/chat_id errado, ou a mensagem foi apagada.Guarde o message_id devolvido pelo método de envio junto com o chat id.
message can't be editedA mensagem não foi enviada pelo bot ou não pode mais ser editada.Envie uma mensagem nova em vez de editar.
can't parse entities: …Marcação de parse_mode quebrada: um < ou & sem escape no HTML, ou um destes caracteres sem escape no MarkdownV2: _ * [ ] ( ) ~ ` > # + - = | { } . !. O texto depois dos dois-pontos indica o offset em bytes.Faça escape do texto vindo do usuário, ou envie sem parse_mode.
message text is emptytext ausente ou vazio, muitas vezes um corpo JSON enviado sem Content-Type: application/json.Confira o valor e a codificação da requisição.
wrong file identifier/HTTP URL specifiedUm file_id de outro bot (file ids são vinculados a um bot), ou uma URL que o Telegram não consegue baixar ou que passa dos limites por URL (5 MB para fotos, 20 MB para outros arquivos).Faça upload de novo como multipart/form-data, ou use um link direto público.
query is too old and response timeout expired or query ID is invalidanswerCallbackQuery ou answerInlineQuery foi chamado tarde demais, duas vezes ou com id errado.Responda logo no início do handler, antes do trabalho lento; depois de reiniciar, ignore callback queries antigos.
not enough rights to send text messages to the chat (fotos, documentos…)O bot está restrito no grupo ou não tem permissão para postar no canal.Dê ao bot a permissão necessária ou direitos de admin.
group chat was upgraded to a supergroup chatO grupo comum virou supergrupo e ganhou um id novo, devolvido em parameters.migrate_to_chat_id.Salve o id novo e repita a requisição com ele.
BUTTON_DATA_INVALID e outros erros de reply markupcallback_data fora de 1–64 bytes (caracteres acentuados ocupam 2–4 bytes cada), ou um reply_markup malformado.Guarde payloads longos no servidor e coloque uma chave curta no callback_data.
member list is inaccessibleUm método de membros foi chamado onde o bot não pode ler a lista de membros, normalmente um canal em que ele não é administrador.Torne o bot administrador, ou não consulte membros ali.

Para reproduzir um erro com segurança, abra o sendMessage no Bot API Tester, digite um chat_id inventado e veja a resposta JSON crua.

401 Unauthorized e 404 Not Found

403 Forbidden: bot was blocked by the user e erros parecidos

O erro 403 significa que o bot não tem permissão para escrever nesse chat. Repetir não adianta; atualize os seus dados.

DescriçãoO que aconteceuO que fazer
bot was blocked by the userO usuário bloqueou ou parou o bot.Marque o usuário como inativo e pare de enviar mensagens. Em chats privados, o bot também recebe um update my_chat_member quando é bloqueado ou desbloqueado.
bot can't initiate conversation with a userO usuário nunca abriu o bot. Bots não podem puxar conversa primeiro.Peça ao usuário para tocar em Iniciar, por exemplo com um link t.me/your_bot.
bot is not a member of the channel chatO bot não está no canal.Adicione o bot ao canal como administrador com permissão de postar.
bot was kicked from the group chatO bot foi removido do grupo (a variante para supergrupo menciona supergroup chat).Tire o chat da sua lista ou peça a um admin para adicionar o bot de novo.
user is deactivatedA conta foi excluída.Remova o usuário da sua lista de envio.

409 Conflict no getUpdates

Erros 413, 429 e 5xx

Código de tratamento de erros com retry_after e migrate_to_chat_id

Este wrapper repete o 429 depois do retry_after, segue o migrate_to_chat_id, faz backoff em 5xx e erros de rede e lança um erro tipado para todo o resto, deixando a decisão com quem chamou. O Python usa requests; a versão JavaScript precisa do Node.js 18+ e roda como arquivo .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):
            # erro de rede ou resposta que não é JSON (ex.: 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 flood control: espere o tempo indicado
            time.sleep(extra["retry_after"])
            continue
        if "migrate_to_chat_id" in extra and "chat_id" in params:
            print(f"chat {params['chat_id']} migrou para {extra['migrate_to_chat_id']}: atualize o banco de dados")
            params["chat_id"] = extra["migrate_to_chat_id"]
            continue
        if code is not None and code >= 500:  # problema do lado do Telegram: backoff
            time.sleep(2 ** attempt)
            continue
        raise TelegramError(method, code, data.get("description", ""), extra)
    raise TelegramError(method, None, "desistindo após várias tentativas")


def notify(chat_id, text):
    try:
        return call("sendMessage", chat_id=chat_id, text=text)
    except TelegramError as e:
        if e.code == 403:
            # bloqueado, removido ou conta desativada: pare de enviar para este chat
            print(f"chat {chat_id} inacessível: {e.description}")
        elif e.code == 400 and "chat not found" in e.description.lower():
            print(f"chat id errado: {chat_id}")
        else:
            raise


notify(123456789, "Olá!")
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 {
      // erro de rede ou resposta que não é JSON (ex.: 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 flood control: espere o tempo indicado
      await sleep(extra.retry_after);
      continue;
    }
    if (extra.migrate_to_chat_id !== undefined && "chat_id" in params) {
      console.log(`chat ${params.chat_id} migrou para ${extra.migrate_to_chat_id}: atualize o banco de dados`);
      params.chat_id = extra.migrate_to_chat_id;
      continue;
    }
    if (code >= 500) { // problema do lado do Telegram: backoff
      await sleep(2 ** attempt);
      continue;
    }
    throw new TelegramError(method, code, data.description ?? "", extra);
  }
  throw new TelegramError(method, null, "desistindo após várias tentativas");
}

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, removido ou conta desativada: pare de enviar para este chat
      console.log(`chat ${chatId} inacessível: ${err.description}`);
    } else if (err.code === 400 && err.description.toLowerCase().includes("chat not found")) {
      console.log(`chat id errado: ${chatId}`);
    } else {
      throw err;
    }
  }
}

await notify(123456789, "Olá!");

Um cuidado: uma requisição que deu timeout do seu lado pode ter sido processada mesmo assim, então repetir um envio depois de um erro de rede pode, de vez em quando, entregar a mensagem duas vezes.

Checklist de depuração

  1. Registre o JSON completo de toda resposta com falha: error_code, description e parameters.
  2. Confira o token com o getMe no Bot API Tester: 401 significa que o problema é o próprio token.
  3. Para chat not found e erros 403, chame getUpdates e compare o chat.id real com o da sua configuração.
  4. Para 409, procure uma segunda instância rodando e confira o getWebhookInfo.

Guias relacionados: como pegar o chat id no Telegram, enviar mensagens e escapar o parse_mode, limites do Telegram Bot API e tratamento do 429 e configurar o webhook.

Perguntas frequentes

O que significa “Bad Request: chat not found” no Telegram?

O bot não enxerga o chat do seu chat_id: o id está errado ou sem o prefixo -100, o usuário nunca iniciou o bot ou o bot não é membro do grupo ou canal. Mande uma mensagem ao bot primeiro e pegue o id no getUpdates.

Como tratar “Forbidden: bot was blocked by the user”?

Não tem como resolver do lado do bot: o usuário bloqueou o bot. Capture o código 403, marque o usuário como inativo no banco e pare de enviar mensagens até ele escrever para o bot de novo.

Por que o getUpdates devolve 409 Conflict?

Ou outro processo está fazendo polling com o mesmo token (terminated by other getUpdates request) ou há um webhook configurado (can't use getUpdates method while webhook is active). Pare a segunda instância ou chame deleteWebhook.

Quanto tempo esperar depois de um 429 Too Many Requests?

Exatamente o que diz parameters.retry_after, em segundos, e depois repita a requisição. Não tente de novo na hora nem fixe um atraso no código: o valor muda de resposta para resposta.

Meu código deve verificar o texto da descrição do erro?

O mínimo possível. A descrição é um texto para humanos que o Telegram pode mudar. Decida primeiro por error_code e parameters, e use busca de substring sem diferenciar maiúsculas na descrição só quando precisar distinguir dois erros com o mesmo código.

O que significa 401 Unauthorized no Bot API?

O token é inválido: foi digitado errado, revogado no @BotFather ou pertence ao outro ambiente (produção vs servidor de testes). Confira com getMe e pegue o token atual em /mybots → API Token.

Como criar um bot no Telegram grátis: do BotFather à primeira mensagem

Aprenda a criar bot no Telegram grátis com o @BotFather: pegue o token, teste com getMe e envie a primeira mensagem com curl e Python.

Como hospedar um bot do Telegram: deploy em VPS, Docker e serverless

Como hospedar e fazer deploy de um bot do Telegram: polling ou webhook, serviço systemd na VPS, Docker, Cloudflare Workers com secret_token e checklist.

Telegram Bot API 10.0–10.5: configurações do bot, widgets, rich messages, mensagens efêmeras, guest mode e mais

Novidades do Telegram Bot API 10.0–10.5: setMySettings e BotFullInfo, widgets HTML, rich messages, mensagens efêmeras e guest mode, com exemplos JSON.

Limites do Telegram Bot API: rate limit, erro 429, tamanho de arquivos e de mensagens

Rate limit do Telegram Bot API na prática: 30 msg/s, 1 msg/s por chat, 20/min em grupos, como tratar 429 e retry_after, limites de arquivo e de texto.

Comandos de bot no Telegram: setMyCommands, escopos e deep links com /start

Configure os comandos do bot do Telegram: /setcommands no @BotFather, setMyCommands com escopos e idiomas, parâmetro do /start e /cmd@bot em grupos.

Teclados de bot no Telegram: inline keyboard, botões de callback e reply keyboard

Botões no bot do Telegram: inline keyboard com callback_data, answerCallbackQuery, editar a mensagem após o clique, reply keyboard e ForceReply.

Integração n8n + Telegram: conecte o bot, dispare workflows e envie mensagens

Conecte o n8n ao Telegram: token do bot como Access Token, webhook do Telegram Trigger com HTTPS público, envio por chat id e soluções para erros comuns.

Como enviar mensagens pela API do Telegram com sendMessage (curl, Python e JavaScript)

Use a API do Telegram para enviar mensagens com sendMessage: exemplos em curl, Python e JavaScript, HTML e MarkdownV2, botões inline e erros comuns.

Telegram bot token: como pegar o token do bot, verificar e revogar

Veja como pegar o token do bot do Telegram no @BotFather, achar o token de um bot existente, testar com getMe e revogar um token vazado.

Como configurar o webhook do bot do Telegram: setWebhook, secret_token e n8n

Configure o webhook do bot do Telegram: requisitos de HTTPS e portas, setWebhook com secret_token, getWebhookInfo, deleteWebhook e erros comuns no n8n.

Chat id do Telegram: como pegar o ID de usuário, grupo, canal e tópico com o seu bot

Descubra o chat id do Telegram para o seu bot: getUpdates em chat privado, grupos, supergrupos (-100), canais e tópicos, e o que fazer se vier vazio.

Bot inline no Telegram: como ativar o modo inline e responder às consultas

Crie um bot inline no Telegram: ative o modo inline no @BotFather ou com setMySettings, trate updates inline_query e responda com answerInlineQuery.

Pagamentos com Telegram Stars em bots: faturas, pre-checkout, reembolsos e assinaturas

Receba pagamentos em Telegram Stars no seu bot: sendInvoice com XTR, pre_checkout_query, successful_payment, reembolsos e assinaturas, com código.

Servidor de teste do Telegram: como testar um bot no ambiente de teste

Use o servidor de teste do Telegram: entre no ambiente de teste, crie um bot de teste, chame a Bot API via /test/ e ative o modo TEST no nosso tester.

Widgets do Telegram para site: login com Telegram, post incorporado, comentários e botão compartilhar

Telegram no seu site: novo login com Telegram (OIDC), Login Widget clássico com checagem do hash, post incorporado, comentários e botão compartilhar.

API JavaScript TelegramWidget: referência, eventos, códigos de erro e limites

Referência da API JavaScript TelegramWidget: propriedades, request(), eventos, códigos de erro, variáveis CSS, widget_query, answerWidgetQuery e limites.

Exemplos de widget do Telegram: HTML completo e bot em Python

Exemplos de widget do Telegram com código completo: card de pedido, contador com widget_query, enquete compartilhada ao vivo e prévia no navegador.

Widgets do Telegram: blocos HTML interativos dentro das mensagens do bot

Widgets do Telegram (Bot API 10.4): o que são, como funcionam sendWidget, chat_data e public_data, onde já rodam e a diferença para Mini Apps.

Como testar uma Mini App do Telegram: do mock no navegador ao app real

Teste sua Mini App do Telegram passo a passo: modo mock no navegador, localhost via túnel HTTPS, ambiente de testes, DevTools e validação do initData.