Telegram Bot API · error code

Telegram error 401: Unauthorized: invalid token specified

ConfigurationHTTP 401401 / 404: token and path

Last verified against Telegram Bot API reference

What Telegram returns
Unauthorized: invalid token specified

What error 401 means

The token in the request path is not even shaped like a bot token, so the Bot API server rejected it before looking it up. In the server source this description is returned when the token starts with 0, is longer than 80 characters, contains a /, has no :, or has a numeric bot ID part that is out of range.

Bot tokens look like 123456789:AA...: the bot's numeric ID, a colon, and a secret. The reference's Authorizing your bot section describes this format and shows requests as https://api.telegram.org/bot<token>/METHOD_NAME.

That makes this different from the one-word Unauthorized, which means a well-formed token was not accepted (revoked or wrong). Here the string is structurally broken: a missing environment variable rendered as undefined, the word bot doubled in the URL, an extra path segment, or the token wrapped in quotes or followed by a newline.

What it looks like

{"ok":false,"error_code":401,"description":"Unauthorized: invalid token specified"}

Why it happens

  • An unset variable was rendered as the literal text undefined or None, which has no colon.
  • The URL was built as /botbot<token> or with an extra slash inside the token segment.
  • Quotes, spaces or a newline were included from a config file.
  • A placeholder such as YOUR_TOKEN was never replaced.

How to fix Telegram error 401

  1. 1Print the token length and the position of the colon (not the token itself) to verify its shape.
  2. 2Build the URL as https://api.telegram.org/bot + token + /getMe and test it.
  3. 3Strip quotes and whitespace when loading the token.
  4. 4Fetch the token from @BotFather again if the stored value is damaged, and check it with the bot token checker.

How to stop it recurring

Validate the token format at startup with a simple pattern (digits, colon, secret) and refuse to start when it fails. Call getMe as a health check in each deploy. Keep tokens out of logs, since they grant full control of the bot.

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 is not even shaped like a bot token, so the Bot API server rejected it before looking it up. In the server source this description is returned when the token starts with 0 , is longer than 80 characters, contains a / , has no : , or has a numeric bot ID part that is out of range. Bot tokens look like 123456789:AA... : the bot's numeric ID, a colon, and a secret.

How do I fix Telegram error 401?

1. Print the token length and the position of the colon (not the token itself) to verify its shape. 2. Build the URL as https://api.telegram.org/bot + token + /getMe and test it. 3. Strip quotes and whitespace when loading the token. 4. Fetch the token from @BotFather again if the stored value is damaged, and check it with the bot token checker .

Stop debugging Telegram by hand

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