pending_update_count in getWebhookInfo: What the Number Means

pending_update_count is one field in the object getWebhookInfo returns, and Telegram's documentation defines it in five words: "Number of updates awaiting delivery". It is an integer because it is a queue depth - not a status, not an error code, not a flag. If you were expecting an object or a list, that is the whole answer: the API is telling you how many updates Telegram is currently holding because it has not been able to hand them to your bot.

curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

{
  "ok": true,
  "result": {
    "url": "https://example.com/telegram",
    "has_custom_certificate": false,
    "pending_update_count": 37,
    "last_error_date": 1755590400,
    "last_error_message": "Wrong response from the webhook: 502 Bad Gateway",
    "max_connections": 40
  }
}

A count of 0 is what a healthy bot looks like: Telegram delivered everything and nothing is waiting. Any other number means updates are queued right now. A single reading is close to meaningless, though - what matters is the direction. Call the endpoint twice, a minute apart.

• Steady at 0 - nothing to fix.
• Small and falling - you are draining a backlog after a blip. Leave it alone.
• Climbing - your endpoint is failing or too slow, and every message a user sends is joining the queue.
• Frozen at a high number - Telegram has most likely stopped retrying. See below.

The count tells you that delivery is failing. It never tells you why. The two fields beside it do, and Telegram defines them precisely: last_error_message is "Error message in human-readable format for the most recent error that happened when trying to deliver an update via webhook", and last_error_date is the Unix time of that error.

Read them together and the diagnosis is usually immediate:

• Count climbing, last_error_message populated - your endpoint is answering, but wrongly. The message names the failure: a 502 means your app is down behind the proxy, a 500 means your handler threw, an SSL error means the certificate chain is incomplete for Telegram even if browsers accept it.
• Count climbing, no error message - you are almost certainly returning 200 but too slowly, or you have two processes competing for the same bot.
• Count high, last_error_date hours old - the failure has stopped being retried. Fix the endpoint, then re-check; nothing arrives until Telegram tries again.
• Count 0 but no messages arriving - this is not a webhook problem at all. Telegram thinks it delivered them. Look at privacy mode in groups, or at your own routing after the request lands.

The single most common mistake is treating a non-zero count as the bug and restarting the app. The count is a symptom. The error message is the bug.

Telegram queues an update whenever your webhook does not accept it, and retries with backoff. The retries do not continue forever - after repeated failures over a period of hours Telegram gives up on that webhook, which is why a count that was climbing can sit frozen while last_error_date stays stuck in the past.

There is a hard ceiling on the whole thing. Telegram's documentation states that "Incoming updates are stored on the server until the bot receives them either way, but they will not be kept longer than 24 hours." That sentence has a consequence people discover the expensive way: a backlog is not preserved indefinitely while you debug over a weekend. Anything older than 24 hours is gone, and no amount of fixing your endpoint brings it back. If the queued updates matter - orders, form answers, support requests - the clock is the reason to treat a climbing count as urgent rather than cosmetic.

The realistic causes, in the order they actually occur:

1. The endpoint is returning a non-2xx. Telegram wants a 200 quickly; anything else is a failed delivery.
2. The endpoint is too slow. Doing the work before responding is the classic error. Acknowledge with 200 immediately, then process the update on a queue.
3. The certificate is incomplete. Telegram is stricter than a browser about intermediate certificates.
4. The URL is stale. A redeploy moved the host and nobody re-registered the webhook, so Telegram is faithfully queueing for an address that no longer exists.
5. Two consumers. A polling process left running alongside the webhook, or a second deployment sharing the token - you will see a 409 conflict here.
6. Throughput ceiling. max_connections "Defaults to 40"; on a genuinely high-volume bot the queue can build simply because you are not draining it fast enough.

You can discard the queue outright. Telegram exposes it as a parameter on two methods, documented identically as "Pass True to drop all pending updates":

# Drop the queue and remove the webhook (switching back to getUpdates)
curl "https://api.telegram.org/bot<TOKEN>/deleteWebhook?drop_pending_updates=true"

# Or re-register the webhook and drop the queue in the same call
curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -d "url=https://example.com/telegram" \
  -d "drop_pending_updates=true"

Be clear about what this does: it deletes user messages your bot never processed. That is the right call when the queue is test traffic, or a flood you have no intention of replaying, or when a stale backlog would make your bot reply to hours-old conversations the moment it recovers - which reads as broken to the user on the other end.

It is the wrong call when those updates are real work. Fix the endpoint first and let Telegram deliver the queue normally; it will, as long as you are inside the 24-hour window. Dropping first because the number is unsightly is how people lose orders.

Note the asymmetry worth knowing: there is no method that clears the queue while leaving the webhook untouched. Both routes change the webhook registration as well - one removes it, one re-sets it.

Work down this list; each step is cheap and rules out the one below it.

1. Read the whole getWebhookInfo response, not just the count. The error message names the fault most of the time.
2. Call your own webhook URL from outside your network with a POST and a JSON body. If you cannot get a fast 200 from the public internet, neither can Telegram.
3. Return 200 before doing the work. Acknowledge, enqueue, process. This alone fixes most slow-endpoint backlogs.
4. Check the certificate chain with an external SSL checker rather than a browser.
5. Confirm the registered URL is the one you are running - compare the url field against your current deployment.
6. Make sure nothing else is consuming the bot - one webhook or one poller, never both.
7. Re-check the count after the fix. It should fall on its own. If it does not move and last_error_date is stale, re-register the webhook to prompt Telegram to resume.
8. Only then consider dropping, and only if you have decided the queued updates are expendable.

If the count is 0 and messages still are not arriving, the problem is elsewhere - our Telegram bot not responding guide covers privacy mode, 409 conflicts and the causes that sit outside webhook delivery, and the Telegram error code reference lists the literal API messages with their fixes.

Every bot that matters should poll getWebhookInfo on a schedule - once a minute is plenty - and alert on two conditions: pending_update_count above a threshold you have picked deliberately, and any change in last_error_date. The second is the more valuable alarm, because it fires on the first failed delivery rather than after a queue has built.

Pick the threshold from your own traffic. A bot handling thousands of messages an hour can show a transient count in the dozens and be perfectly healthy; a quiet internal bot sitting at 15 has been broken for a while. The absolute number means nothing without your baseline - which is the reason to record it continuously rather than check it during an incident.

The 24-hour ceiling is what turns this from hygiene into something worth paging on. An unmonitored webhook that fails on a Friday evening has silently discarded a day of customer messages by Saturday night, and nothing in your logs will ever show what they said. Related reading: the cross-platform webhook debugging guide for the same failure shapes on Meta, Slack and Discord.