Telegram error 400: Bad Request: secret token contains illegal characters
Last verified against Telegram Bot API reference
Bad Request: secret token contains illegal charactersWhat error 400 means
The secret_token you passed to setWebhook includes characters that are not allowed. The reference is explicit: secret_token is 1-256 characters, and only A-Z, a-z, 0-9, _ and - are allowed. Anything else, including +, /, =, spaces, dots or a trailing newline, is rejected.
The usual cause is generating the secret with standard Base64 encoding (which uses +, / and = padding) or with a password generator that includes symbols. A token over 256 characters fails with a sibling message, secret token is too long.
Nothing was registered. The secret matters because Telegram sends it back in the X-Telegram-Bot-Api-Secret-Token header on every webhook request, which is how your endpoint can tell genuine updates from forged ones. Fixing the format restores that protection.
What it looks like
{"ok":false,"error_code":400,"description":"Bad Request: secret token contains illegal characters"}Why it happens
- The secret was produced with standard Base64, which includes
+,/and=. - A password generator added punctuation or spaces.
- A trailing newline from a secrets file was included.
- The secret was URL-encoded, adding
%characters. - Quotes kept around the value when it was read from a shell or .env file, so the token arrives as
"abc123"with the quote characters included.
How to fix Telegram error 400
- 1Generate the secret with only letters, digits, underscore and hyphen, for example URL-safe Base64 without padding or hex.
- 2Trim whitespace before sending.
- 3Call setWebhook again with the corrected secret and confirm your endpoint checks the header value.
- 4Update the stored copy your webhook handler compares against, so valid requests are not rejected after the change.
- 5Generate a safe value directly:
python -c "import secrets; print(secrets.token_urlsafe(32))"ornode -e "console.log(require('crypto').randomBytes(32).toString('hex'))"; both produce only allowed characters. - 6After setWebhook succeeds, check that each incoming update carries the same value in the
X-Telegram-Bot-Api-Secret-Tokenheader before you trust it.
How to stop it recurring
Validate the secret against the documented character set at startup, and generate it once per bot with a URL-safe generator. Compare the incoming header in constant time in your webhook handler and reject requests without it. Webhook constraints are listed under webhook limits.
Official reference: Telegram Bot API reference. See all Telegram error codes or the Telegram limits and quotas.
Related codes
- 400: Bad Request: invalid webhook URL specifiedBad Request: invalid webhook URL specified
- 400: Bad Request: bad webhook: HTTPS url must be provided for webhookBad Request: bad webhook: HTTPS url must be provided for webhook
- 409: Conflict: terminated by setWebhook requestConflict: terminated by setWebhook request
Error 400 - quick answers
What does Telegram error 400 mean?
The secret_token you passed to setWebhook includes characters that are not allowed. The reference is explicit: secret_token is 1-256 characters, and only A-Z , a-z , 0-9 , _ and - are allowed. Anything else, including + , / , = , spaces, dots or a trailing newline, is rejected.
How do I fix Telegram error 400?
1. Generate the secret with only letters, digits, underscore and hyphen, for example URL-safe Base64 without padding or hex. 2. Trim whitespace before sending. 3. Call setWebhook again with the corrected secret and confirm your endpoint checks the header value. 4. Update the stored copy your webhook handler compares against, so valid requests are not rejected after the change. 5. Generate a safe value directly: python -c "import secrets; print(secrets.token_urlsafe(32))" or…
Stop debugging Telegram by hand
Connect the channel through Conferbot: tokens, webhooks and retries are handled, failures show as readable status.