Telegram Bot API · error code

Telegram error 400: Bad Request: can't parse reply keyboard markup JSON object

ConfigurationHTTP 400400 Bad Request: identifiers, content and rights

Last verified against Telegram Bot API reference

What Telegram returns
Bad Request: can't parse reply keyboard markup JSON object

What error 400 means

The reply_markup parameter reached the Bot API server as a string that is not valid JSON. The server decodes reply_markup before anything else, and when that decode fails it returns this description without looking at the keyboard's contents.

The Bot API reference describes reply_markup as a JSON-serialized object. With application/json requests you send it as a nested object and the client handles it. With query strings, application/x-www-form-urlencoded or multipart/form-data (the format used for file uploads) every parameter is a string, so you must serialize the keyboard yourself. Passing a language-level object there sends something like [object Object] or a Python dict repr with single quotes, and decoding fails.

If the JSON parses but has the wrong shape, you get a different message such as object expected as reply markup or a button-level parse error. This one is strictly about syntax: quotes, escaping, trailing commas, or double-encoding that leaves the value wrapped in an extra string.

What it looks like

{"ok":false,"error_code":400,"description":"Bad Request: can't parse reply keyboard markup JSON object"}

Why it happens

  • A keyboard object was placed in a form or multipart request without JSON.stringify or json.dumps.
  • Python's str() of a dict was sent, producing single quotes and True instead of valid JSON.
  • The JSON was URL-encoded twice, or not encoded at all in a GET query string.
  • A hand-written template left a trailing comma or an unescaped quote in a button label.

How to fix Telegram error 400

  1. 1Print the exact reply_markup value sent on the wire and run it through a JSON validator.
  2. 2Serialize with a real JSON encoder whenever the request body is form-encoded or multipart.
  3. 3Prefer sending the whole request as application/json when no file upload is involved.
  4. 4Escape quotes and backslashes in button text through the encoder rather than by hand.

How to stop it recurring

Centralize keyboard serialization in one function and use it for both JSON and multipart requests, so uploads with keyboards do not take a separate code path. Test a sendPhoto with an inline keyboard in CI; it is where this error usually first appears. The keyboard builder emits valid reply_markup JSON to compare against.

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

Related codes

Error 400 - quick answers

What does Telegram error 400 mean?

The reply_markup parameter reached the Bot API server as a string that is not valid JSON. The server decodes reply_markup before anything else, and when that decode fails it returns this description without looking at the keyboard's contents. The Bot API reference describes reply_markup as a JSON-serialized object. With application/json requests you send it as a nested object and the client handles it.

How do I fix Telegram error 400?

1. Print the exact reply_markup value sent on the wire and run it through a JSON validator. 2. Serialize with a real JSON encoder whenever the request body is form-encoded or multipart. 3. Prefer sending the whole request as application/json when no file upload is involved. 4. Escape quotes and backslashes in button text through the encoder rather than by hand.

Stop debugging Telegram by hand

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