Erros do Telegram Bot API: o que cada erro significa e como resolver
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"
}
| Campo | Significado |
|---|---|
ok | false em toda requisição que falhou. |
error_code | Inteiro, espelha o status HTTP: 400, 401, 403, 404, 409, 413, 429, 5xx. |
description | Explicação em texto puro, geralmente com o nome do status na frente: Bad Request:, Forbidden:, Conflict:. |
parameters | ResponseParameters 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:
- decide primeiro pelo
error_code(400, 403, 429, 5xx); - usa
parameters.retry_aftereparameters.migrate_to_chat_idsempre que existirem, em vez de extrair números da descrição; - compara trechos da descrição só quando precisa distinguir erros com o mesmo código, sem diferenciar maiúsculas e com um fallback seguro quando nada bate;
- registra a descrição completa no log, para que mensagens novas apareçam em vez de sumirem.
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ção | Causa | Solução |
|---|---|---|
chat not found | chat_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_INVALID | O 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 modified | Um 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 found | Par 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 edited | A 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 empty | text 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 specified | Um 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 invalid | answerCallbackQuery 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 chat | O 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 markup | callback_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 inaccessible | Um 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
401 Unauthorized: o token está errado ou foi revogado. Também acontece quando um token de produção é enviado ao servidor de testes ou vice-versa. Confira o token comgetMe; se ele vazou e foi revogado, pegue o novo no @BotFather.404 Not Found: a URL não segue o formatohttps://api.telegram.org/bot<token>/METHOD_NAME. Causas típicas: falta o prefixobotantes do token, o token tem espaços ou quebras de linha, ou o nome do método está digitado errado. Nomes de métodos não diferenciam maiúsculas, entãosendmessagefunciona, massendMesagenão.
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ção | O que aconteceu | O que fazer |
|---|---|---|
bot was blocked by the user | O 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 user | O 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 chat | O bot não está no canal. | Adicione o bot ao canal como administrador com permissão de postar. |
bot was kicked from the group chat | O 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 deactivated | A conta foi excluída. | Remova o usuário da sua lista de envio. |
409 Conflict no getUpdates
Conflict: terminated by other getUpdates request; make sure that only one bot instance is running— dois processos fazem polling com o mesmo token: um terminal esquecido, um segundo container, um deploy que subiu antes de o antigo parar. Mantenha exatamente um poller por token.Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first— o bot tem um webhook, e o getUpdates não funciona enquanto ele estiver configurado. ChamedeleteWebhook, ou mantenha o webhook e pare o polling.
Erros 413, 429 e 5xx
413 Request Entity Too Large: o upload é maior do que a API aceita. Bots podem enviar até 50 MB peloapi.telegram.org; um servidor local do Bot API eleva isso para 2000 MB.429 Too Many Requests: retry after N: flood control. Espereparameters.retry_aftersegundos e repita. Depois diminua o ritmo: cerca de 1 mensagem por segundo por chat, 20 por minuto num grupo e cerca de 30 por segundo no total. Os números e as estratégias de fila estão no guia de limites.500,502 Bad Gatewaye outros 5xx: problema do lado do Telegram ou no caminho até ele. Tente de novo com backoff exponencial. O corpo de um 502 pode ser uma página que não é JSON, então não suponha queresponse.json()sempre funciona.
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
- Registre o JSON completo de toda resposta com falha:
error_code,descriptioneparameters. - Confira o token com o getMe no Bot API Tester: 401 significa que o problema é o próprio token.
- Para
chat not founde erros 403, chamegetUpdatese compare ochat.idreal com o da sua configuração. - 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.
Guias relacionados
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.