Errors & Limits

Error envelope

{
  "ok": false,
  "error_code": 403,
  "code": "CHAT_FORBIDDEN",
  "description": "User has not started this bot."
}

error_code mirrors the HTTP status code. code is stable enough for program logic. description is for humans and may change.

Common errors

HTTP	Code	Meaning
400	`BAD_REQUEST`	Missing or invalid parameters.
401	`UNAUTHORIZED`	Missing, malformed, unknown, disabled, or owner-banned bot token.
403	`CHAT_FORBIDDEN`	Bot cannot send to this chat.
403	`BOT_BLOCKED`	User or bot has blocked the other side.
403	`METHOD_NOT_ALLOWED_FOR_TIER`	Bot tier does not allow this method.
403	`MESSAGE_FORBIDDEN`	Bot tried to edit/delete a message it does not own.
404	`CHAT_NOT_FOUND`	Target chat does not exist or is invisible to the bot.
409	`GATEWAY_ACTIVE`	Polling is not allowed while Gateway is active.
413	`PAYLOAD_TOO_LARGE`	Uploaded media exceeds the method limit.
429	`RATE_LIMITED`	Per-minute or daily quota exceeded.
500	`INTERNAL`	Temporary server failure.

Rate-limit errors include retry_after seconds when available.

Default quota tiers

Quotas are intentionally conservative and may change while Bot API is in early access.

Tier	Messages / min	Messages / day	Polls / min	Polls / day	Chat actions / min	Edit/delete
`free`	20	1,000	30	10,000	60	no
`pro`	60	10,000	60	50,000	180	yes
`team`	100	25,000	100	100,000	300	yes
`official`	120	50,000	120	200,000	600	yes

Gateway connection attempts are also rate-limited per minute. The number of simultaneous Gateway connections is configured per bot by the platform.

Retry guidance

Retry 429 only after retry_after.
Retry 500 with exponential backoff and jitter.
Do not retry 400 without changing the request.
Treat 401 as a token/configuration problem and stop until credentials are fixed.
Treat 403 as a permission problem. Retrying will not help until the user or admin changes state.

Idempotency

Update delivery is at least once. Deduplicate received updates by update_id.

Send APIs are not idempotent by default. If your agent may retry after a network timeout, keep your own outgoing operation id and avoid sending duplicate user visible messages.