Error Reference

Telegram API Error Reference

Comprehensive reference for Telegram API errors. Find solutions and troubleshoot common integration issues.

16 error codes•5 categories•Bot API

← Telegram View API Documentation

Error Categories

Authentication

3 errors

Chat

3 errors

Rate Limiting

3 errors

Media

4 errors

Content

3 errors

All Error Codes

#Authentication

bot_blockedrefresh-token

The bot was blocked by the user or removed from the chat.

Solution:

The user has blocked your bot or removed it from the channel/group. Ask the user to unblock the bot or add it back as an administrator.

bot_kickedrefresh-token

The bot was kicked from the chat.

Solution:

Your bot was removed from this channel or group. The bot needs to be re-added as an administrator with posting permissions.

unauthorizedrefresh-token

Bot token is invalid or expired.

Solution:

There's an issue with the bot configuration. Please contact Zernio support to resolve this issue.

#Chat

chat_not_founduser-error

The specified chat does not exist or the bot is not a member.

Solution:

The channel or group ID is invalid or the bot is not a member. Verify the chat ID is correct and the bot has been added as an administrator.

chat_write_forbiddenuser-error

The bot does not have permission to send messages in this chat.

Solution:

The bot lacks posting permissions in this channel/group. Ensure the bot is an administrator with 'Post Messages' permission enabled.

not_enough_rightsuser-error

The bot does not have sufficient admin rights.

Solution:

The bot needs additional admin permissions. Check that the bot has rights to post messages, send media, and any other required permissions.

#Rate Limiting

flood_controlretry

Too many requests. Telegram's flood control limit reached.

Solution:

You've exceeded Telegram's rate limits. Wait for the specified retry_after seconds before sending more messages. Zernio handles this automatically with queuing.

too_many_requestsretry

Rate limit exceeded. Please slow down.

Solution:

Too many API calls in a short period. Telegram limits are approximately 30 messages per second to different chats. Implement proper rate limiting.

retry_afterretry

Rate limited. Must wait before sending more messages.

Solution:

Telegram is enforcing a cooldown period. Wait for the specified duration before retrying. Zernio automatically handles this with exponential backoff.

#Media

file_too_largeuser-error

The file is too large to upload.

Solution:

Telegram has file size limits: photos up to 10MB, documents up to 50MB, videos up to 50MB. Compress your file or use a smaller version.

wrong_file_typeuser-error

The file type is not supported or the file is corrupted.

Solution:

Ensure your file is in a supported format (JPEG, PNG for images; MP4 for videos). Re-export the file and try again.

photo_invaliduser-error

The photo could not be processed.

Solution:

The image file is corrupted or in an unsupported format. Use JPEG or PNG format and ensure the image is not corrupted.

video_invaliduser-error

The video could not be processed.

Solution:

The video file is corrupted or uses an unsupported codec. Convert to MP4 with H.264 codec and AAC audio.

#Content

message_too_longuser-error

The message text exceeds the maximum length (4096 characters).

Solution:

Telegram messages are limited to 4096 characters. Shorten your message or split it into multiple messages.

caption_too_longuser-error

The media caption exceeds the maximum length (1024 characters).

Solution:

Media captions are limited to 1024 characters. Use a shorter caption or send the additional text as a separate message.

media_group_invaliduser-error

Invalid media group. Albums must contain 2-10 items of the same type.

Solution:

Media albums require 2-10 photos or videos. Ensure all items are the same type (all photos or all videos) and within the count limit.

Best Practices

Error Handling

→Verify bot has admin permissions
→Handle rate limits with exponential backoff
→Check media file sizes before upload
→Ensure URLs are publicly accessible

Prevention Tips

→Keep text messages under 4096 characters
→Keep captions under 1024 characters
→Compress photos to under 10MB
→Compress videos to under 50MB

Need Help with Telegram Integration?

Our API handles error scenarios automatically with smart retry logic and detailed logging.

Start Building View Documentation