Skip to content

Error Handling & Status Codes

When a request cannot be processed due to validation errors, authorization issues, or rate limits, the CodeMeet Bot API responds with a structured JSON error object:

{
  "ok": false,
  "error_code": 400,
  "description": "Bad Request: chat not found"
}

Status Codes Reference Table

Status Code Error Title Common Root Cause Recommended Action
400 Bad Request Missing required parameters, invalid JSON, or malformed keyboard Verify JSON structure and parameter types against docs
401 Unauthorized Token is invalid, mistyped, or revoked via /revoke Verify token or generate a new one via @BotFather
403 Forbidden User has not started the bot, or bot lacks admin role in group Ask user to send /start or promote bot to group administrator
404 Not Found Method or message ID does not exist Check method name spelling and target message sequence
409 Conflict Polling while webhook is configured, or duplicate username Call deleteWebhook before polling
413 Request Entity Too Large Request body exceeds maximum allowed size (1 MB) Reduce payload size
429 Too Many Requests Hit rate limit quota Pause execution and retry after parameters.retry_after
502 Bad Gateway Backend relay temporarily unreachable Implement exponential backoff retry logic

Specific Common Errors Explained

1. the user must start the bot first (403 Forbidden)

{
  "ok": false,
  "error_code": 403,
  "description": "Forbidden: the user must start the bot first"
}
Explanation: For privacy and spam prevention, bots cannot initiate unsolicited private chats. The user must first click Start or send /start.

2. bot must be an administrator (403 Forbidden)

Explanation: The bot attempted an action (such as pinning a message or sending to a channel) without administrative permissions.

3. can't parse entities (400 Bad Request)

Explanation: Unclosed HTML tags (e.g. <b> without </b>) or unescaped Markdown special characters when using parse_mode.

4. Rate Limiting (429 Too Many Requests)

{
  "ok": false,
  "error_code": 429,
  "description": "Too Many Requests: retry after 5",
  "parameters": {
    "retry_after": 5
  }
}
Handling: Extract retry_after and delay further requests accordingly.