Telegram Bot API · error code

Telegram error 504: 504 Gateway Timeout

RetryableHTTP 504502 / 504: Telegram-side

Last verified against Telegram Bot API reference

What Telegram returns
504 Gateway Timeout (HTML body from the api.telegram.org front end; not a JSON Bot API response)

What error 504 means

A 504 from api.telegram.org means the front-end proxy waited for the Bot API backend and gave up. Like 502, it is not a documented Bot API error and the body is typically HTML, so treat it as an infrastructure signal rather than a response to parse. It clusters around the same causes: brief Telegram-side incidents, or very slow operations such as large uploads that time out before the backend answers.

The important question after a 504 is whether the request took effect. For a sendMessage that timed out, the message may or may not have been delivered; Telegram does not provide idempotency keys, so a blind retry can duplicate. For reads (getMe, getChat, getUpdates) a retry is always safe.

Long-polling getUpdates with a large timeout value can also surface gateway timeouts if your HTTP client's own timeout is shorter than the long-poll window, which is a client configuration issue rather than a Telegram one.

What it looks like

HTTP/1.1 504 Gateway Time-out
Content-Type: text/html

<html><head><title>504 Gateway Time-out</title></head>...

Why it happens

  • Telegram backend slowness or a short incident.
  • Large multipart uploads near the size limit on a slow link.
  • Client-side HTTP timeout shorter than the getUpdates long-poll timeout, which looks similar in logs.

How to fix Telegram error 504

  1. 1Retry reads immediately with backoff; for sends, retry with care or deduplicate on your side.
  2. 2Set the HTTP client timeout comfortably above the long-poll timeout you pass to getUpdates.
  3. 3For uploads, reuse file_id where possible and keep files well under the limits.
  4. 4Log the status and a short excerpt of the body so 504s are distinguishable from JSON errors.

How to stop it recurring

Build sends as idempotent operations on your side (a per-message key and a 'sent' flag written after success), so that retries after a timeout cannot double-send. Keep the polling client's timeout configuration explicit and documented so the two timeouts never drift apart.

python-telegram-bot wraps client-side timeouts in telegram.error.TimedOut (a NetworkError), which is easy to confuse with a server-side 504 in logs; the distinction matters because TimedOut can occur while the request still succeeded. Treat both like the 502 case: backoff, dedupe sends, and check Telegram bot not responding if updates also stop flowing.

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

Related codes

Error 504 - quick answers

What does Telegram error 504 mean?

A 504 from api.telegram.org means the front-end proxy waited for the Bot API backend and gave up. Like 502, it is not a documented Bot API error and the body is typically HTML, so treat it as an infrastructure signal rather than a response to parse. It clusters around the same causes: brief Telegram-side incidents, or very slow operations such as large uploads that time out before the backend answers.

How do I fix Telegram error 504?

1. Retry reads immediately with backoff; for sends, retry with care or deduplicate on your side. 2. Set the HTTP client timeout comfortably above the long-poll timeout you pass to getUpdates . 3. For uploads, reuse file_id where possible and keep files well under the limits. 4. Log the status and a short excerpt of the body so 504s are distinguishable from JSON errors.

Can I retry after error 504?

Yes - this is a retryable condition. Back off (start around one second and double on each attempt, with jitter) and watch for a retry-after hint from the platform before resending.

Stop debugging Telegram by hand

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