English
Errors & Fixes
Errors are part of life, especially a developer's life. Every Zate error has the same shape:
json
{
"statusCode": 404,
"message": "session not found"
}Match the statusCode and message you got against the tables below, then follow the fix.
400: Something's Off with the Request
message | Meaning | Fix |
|---|---|---|
invalid header | The id or session-id header is missing. | Send both headers on every endpoint except POST /session and media links. |
invalid phone, username, user, group or channel | Send Message without a receiver. | Fill in one of phone, username, user, group, or channel. |
invalid phone, username, user or group | Send Typing without a receiver. | Fill in one of phone, username, user, or group. |
invalid receiver | The phone number has fewer than 8 digits after tidying. | Check the format in Core Concepts. |
invalid chat | The username isn't valid, for example it has a space or doesn't start with a letter. | Check the spelling. @ and t.me links are fine. |
chat not found | The username doesn't exist, or your account doesn't know that ID yet. | Use a username, or get the right ID from Get Groups, Get Channels, or Get Group Members. |
phone is not on telegram or hidden by its privacy settings | The number isn't on Telegram, or its owner hides from phone number lookups. | Use a username or user ID. |
channel not found | The ID or username exists but isn't a channel (a group, for example), or you haven't joined that channel. | Join it from Telegram first, or get the channel ID from Get Channels. |
group not found | The ID or username exists but isn't a group (a channel, for example), or you haven't joined that group. | Join it from Telegram first, or get the group ID from Get Groups. |
password is not required | Submit Password was called while the session isn't waiting for a password. | Check isPasswordRequired in Get Session first. |
invalid password | Wrong two-step verification password. | Try again. The hint is in passwordHint. |
url and token must be both filled, or both empty to turn the webhook off | Set Webhook got only one of the two. | Fill in both, or leave both empty to turn the webhook off. |
url must be an http or https url | The webhook URL isn't valid. | Use a full URL starting with http:// or https://. |
type must be one of the following values: ... | Unknown type value. | Use one of the values listed in the error message. |
text should not be empty | type is text but text is empty. | Fill in text. |
image should not be empty (also video, audio, and so on) | The media object for that type is missing. | Send the object, e.g. image for type: "image". |
image.url should not be empty, video.duration must be a positive number, and so on | A required field inside the object is empty or invalid. | Check the object tables in Send Message. |
parseMode must be one of the following values: markdown, html | Unknown parseMode value. | Use markdown, html, or leave it out. |
privacy must be one of the following values: ... | Unknown privacy value in Send Status. | Use contacts, everyone, or close_friends. |
groupId should not be empty / channelId should not be empty | A required query parameter is missing. | Add the parameter to the URL. |
404: Not Found
message | Meaning | Fix |
|---|---|---|
session not found | Wrong id or session-id, or the session was deleted. | Double-check both headers. If they're right, the session is gone, so create a new session. |
media not found | The media link was tampered with, or the message was deleted. | Get a fresh link from Get Channel Messages or the webhook. |
A session can disappear for a few reasons: the QR wasn't scanned within 3 minutes, the session was disconnected for more than 30 minutes, or you deleted it yourself. Details are in the Session Lifecycle.
500: Something Went Wrong While Processing
message | Meaning | Fix |
|---|---|---|
session not connected | The session exists but isn't connected to Telegram right now. | Check Get Session. If qrcode is filled in, scan again. If isPasswordRequired: true, send the password. If both are empty, wait a moment while Zate reconnects. |
session not found | The session is in the database but not active on the server yet, for example right after a restart. | Wait a few seconds and try again. If it keeps failing, reset or create a new session. |
error parser file from url ... | The media couldn't be downloaded from the URL you gave. | Make sure the URL is public, points straight at the file, and the server responds quickly. |
send timeout after 240s | Sending took longer than 4 minutes. | Use a smaller file or a faster file server. |
error compress image: ... | The image couldn't be processed. | Make sure the URL is a valid image (JPG, PNG, or WebP). |
400: ERROR_NAME (caused by ...) and similar | An error straight from Telegram. | See Errors from Telegram below. |
internal server error or anything else | Something's wrong on the server. | Try again in a bit. If it persists, let us know. |
503: Telegram Asks You to Wait
Only from Get Media. The response carries a Retry-After header with the number of seconds to wait.
message | Meaning | Fix |
|---|---|---|
telegram asked to wait 120s | Telegram is rate-limiting media requests for your account. | Wait as long as Retry-After says, then open it again. |
telegram did not answer the media request in time | Telegram didn't answer within 30 seconds. | Try again shortly. |
Errors from Telegram
When Telegram itself refuses, its message is passed through as is, in the format code: ERROR_NAME (caused by request), for example:
json
{
"statusCode": 500,
"message": "403: CHAT_WRITE_FORBIDDEN (caused by messages.SendMessage)"
}The ones you'll meet most often:
| Error | Meaning |
|---|---|
PEER_FLOOD | Your account is limited for looking like spam. Check @SpamBot and reread Before You Start. |
A wait of N seconds is required | Too many requests, Telegram wants you to wait N seconds. Waits under a minute are waited out automatically, longer ones come back as an error. |
CHAT_WRITE_FORBIDDEN | You're not allowed to send messages in that group or channel. |
CHAT_ADMIN_REQUIRED | Admin rights needed, for example to post in someone else's channel or to list the members of a group that hides them. |
USER_IS_BLOCKED / YOU_BLOCKED_USER | That person blocked you, or you blocked them. |
PRIVACY_PREMIUM_REQUIRED | They only accept messages from contacts or Telegram Premium users. |
MESSAGE_TOO_LONG / MEDIA_CAPTION_TOO_LONG | The text or caption is too long. |
SLOWMODE_WAIT_N | The group has slow mode on, wait N seconds before sending again. |
STORIES_TOO_MUCH | Your account's story limit is used up. |
Frequently Asked Questions
qrcode stays empty, what now?
For the first few seconds after Create Session or Reset Session, that's normal. Call Get Session every 2–3 seconds. If isPasswordRequired becomes true, the QR was already scanned and you just need to submit the password.
Telegram says the QR expired when I scan it.
The QR changes roughly every 30 seconds, so you probably scanned an old one. Get the newest QR from Get Session and scan again.
I scanned the QR, but isConnected is still false.
Check isPasswordRequired. If it's true, your account uses two-step verification and Zate is waiting for the password. If it's false, wait a few seconds and check again.
Sending to a phone number keeps failing.
On Telegram, people can hide from phone number lookups, and many do. Use username or user (ID) instead, they're far more reliable.
I suddenly have to scan the QR again, without doing anything.
Usually because the Zate device was removed from Settings → Devices, or Telegram ended the session. Zate prepares a new QR right away, but it's only valid for 3 minutes. If you miss it, the session is deleted and you'll need a new one.
My webhook never receives anything.
Check one by one: the URL is reachable from the internet, your server compares x-token with the same token, and it answers 2xx within 10 seconds. Also remember the webhook only sends private chat events, and messages from before the webhook was set aren't sent. Details in Receiving Messages.