telegram-sender: Known Failure Modes

Component: telegram-sender Tags: telegram-sender,delivery,telegram-api,rabbitmq,dlq,cooldown Author: phase-f-migration Updated: 4/26/2026, 3:47:42 PM

telegram-sender consumes from rpe.telegram.response queue and delivers messages via the Telegram Bot API.

FAILURE MODES:

1. Telegram Bot API unreachable — HTTPS call to api.telegram.org fails. Delivery fails with network error. Exponential backoff retry (3 attempts). On exhaustion, message goes to DLQ (rpe.telegram.response.dlq).

2. Invalid bot token — Telegram API returns 401. Bot token in config may have been revoked or is wrong for this bot_id. Check bots table in zoey_core.

3. Telegram rate limiting — API returns 429. Backoff + retry. If persistent, the bot may be flooding the API.

4. Message too long — Telegram API returns 400 with "message is too long". Agent response exceeded Telegram limit (4096 chars). Should be caught upstream but can slip through.

5. RabbitMQ disconnect — cannot consume from rpe.telegram.response. Responses accumulate in queue. Consumer count drops to 0.

6. Redis cooldown / mute cache hit — message withheld by rate limiter. Check Redis keys with prefix rpe: for the chat_id.

7. DLQ accumulation — rpe.telegram.response.dlq growing means persistent delivery failures. Check Telegram API status and bot token validity.

FIRST CHECKS:

RabbitMQ: consumer count on rpe.telegram.response (should be 1). Depth rising = telegram-sender not consuming.
DLQ depth: check rpe.telegram.response.dlq — any messages there = delivery failures.
Can you reach api.telegram.org from the host? (network connectivity check)
Redis: check rpe:{chat_id}:cooldown keys — are target chats muted or rate-limited?
Check bot token in bots table for the affected bot_id.

DEPLOY TYPE: image-copy. Changes require rebuild + up -d.