Telegram Bot API · error code

Telegram error 401: Unauthorized

ConfigurationHTTP 401401 / 404: token and path

Last verified against Telegram Bot API reference

What Telegram returns
Unauthorized

What error 401 means

The token in the request path (/bot<token>/method) is not a valid bot token. Telegram returns HTTP 401 with the one-word description Unauthorized for every method, including getMe. The token is either malformed, revoked, or belongs to a bot that was deleted.

Telegram does not distinguish 'wrong token' from 'revoked token' in the response, so you cannot tell which from the error alone. What you can tell is that nothing downstream (chat IDs, permissions, rate limits) is involved: authentication failed before any of that was evaluated.

Because the token is part of the URL, anything that alters the path produces this error: a trailing newline from a secrets file, quotes copied from a shell export, URL-encoding of the colon, or the token for a different environment. Regenerating the token in @BotFather immediately invalidates the previous one, so a 401 that appears out of nowhere on a working bot usually means someone rotated the token and the deployment still has the old value.

Libraries make this failure loud in different ways. python-telegram-bot raises telegram.error.InvalidToken (its 403 sibling, Forbidden, was named Unauthorized in v13 and earlier, which still confuses old Stack Overflow answers). aiogram v3 raises TelegramUnauthorizedError. grammY throws a GrammyError with error_code: 401 and logs a hint that the token is wrong and should be checked with @BotFather. Telegraf and node-telegram-bot-api fail at launch with 401: Unauthorized / ETELEGRAM: 401 Unauthorized in the error message.

What it looks like

{"ok":false,"error_code":401,"description":"Unauthorized"}

Why it happens

  • The token was regenerated or revoked via @BotFather (/revoke or /token) and the old one is still deployed.
  • Whitespace, newline or quote characters wrapped around the token in an environment variable.
  • The staging or a colleague's token was deployed, or the variable name differs between environments.
  • The token was truncated when copied (it contains a colon and is typically 40+ characters).
  • The bot itself was deleted in @BotFather.

How to fix Telegram error 401

  1. 1Call https://api.telegram.org/bot<TOKEN>/getMe with the exact value from the failing environment; a good token returns your bot's username. The token checker runs this test and explains the result.
  2. 2Print repr(token) (or equivalent) to expose hidden whitespace and quotes; trim it.
  3. 3Compare the token character-for-character with what @BotFather shows under /token; check especially the part before the colon (the bot ID).
  4. 4If getMe fails with a freshly copied token, generate a new one in @BotFather and redeploy.
  5. 5Audit which environments hold which token and rotate anything that has leaked.

How to stop it recurring

Load the token from a secrets manager that does not add newlines, and validate it at startup with getMe, failing fast on 401 rather than starting a bot that cannot authenticate. Never bake tokens into images or repositories. When rotating, deploy the new token before revoking the old one so there is no window where production runs unauthenticated. Token mix-ups and the deploy patterns that cause them are cause 6 in Telegram bot not responding.

Official reference: Telegram Bot API reference. See all Telegram error codes or the Telegram limits and quotas.

Related codes

Error 401 - quick answers

What does Telegram error 401 mean?

The token in the request path ( /bot<token>/method ) is not a valid bot token. Telegram returns HTTP 401 with the one-word description Unauthorized for every method, including getMe . The token is either malformed, revoked, or belongs to a bot that was deleted. Telegram does not distinguish 'wrong token' from 'revoked token' in the response, so you cannot tell which from the error alone.

How do I fix Telegram error 401?

1. Call https://api.telegram.org/bot<TOKEN>/getMe with the exact value from the failing environment; a good token returns your bot's username. The token checker runs this test and explains the result. 2. Print repr(token) (or equivalent) to expose hidden whitespace and quotes; trim it. 3. Compare the token character-for-character with what @BotFather shows under /token; check especially the part before the colon (the bot ID). 4. If getMe fails with a freshly copied token,…

Stop debugging Telegram by hand

Connect the channel through Conferbot: tokens, webhooks and retries are handled, failures show as readable status.