# Token Diagnostic Quick Reference

## getMe Response Codes

| Response | Meaning | Action |
|---|---|---|
| `ok:true, result:{id...,is_bot:true}` | Token valid, bot working | No action needed |
| `error_code:401` | Token revoked by BotFather | Regenerate — `/token` in BotFather |
| `error_code:404` | Bot doesn't exist on Telegram | Regenerate — `/newbot` in BotFather |
| `ConnectError / Timeout` | Network issue — can't reach Telegram | Check DNS, firewall, internet connectivity |

## 404 Differential

A 404 can mean:
1. **Token malformed/clipped** — missing characters, truncated at colon, corrupted by config edit
2. **Bot deleted** — bot was removed via BotFather or Telegram pruned it
3. **Token never valid** — the bot ID portion may be fabricated or mistyped

### How to distinguish

Passes format regex `\d+:[A-Za-z0-9_-]{30,}`?

| Format OK? | `.env` modified recently? | Last Telegram activity | Likely cause |
|---|---|---|---|
| No | N/A | N/A | Corrupted/malformed token — fix the value |
| Yes | Yes | Before `.env` mtime | Token changed during `.env` edit to a bad value |
| Yes | No | Before restart | Bot was deleted/revoked on Telegram side |
| Yes | No | Ongoing | Token format error (unlikely — regex is permissive) |

## Token Location Priority

Hermes gateway reads `TELEGRAM_BOT_TOKEN` from **environment** (loaded from `.env` by the Hermes env loader). `config.yaml`'s `gateway.telegram.token` is NOT read by the gateway process — it's only used by the `hermes setup` web UI.

**Always check `.env` for the real token.** If `.env` doesn't have `TELEGRAM_BOT_TOKEN`, the gateway won't have it regardless of what `config.yaml` says.