ERROR HANDLING

When something goes wrong, the server replies with a single-field object carrying a numeric code:

json
{
  "error": 199999
}

⚠️ Codes 199999 and 199997 close the WebSocket. Reconnect and re-authenticate before sending anything else — every other code leaves the session open.

Authentication

Code	Meaning	What to do
`100001`	No authentication. You sent something before `TOKEN_AUTH`.	Authenticate first — see AUTHENTICATION.
`100099`	Authentication error. The token was rejected.	Check the token. If it was regenerated, the old one is dead — fetch the new one.

Permissions

Code	Meaning	What to do
`160017`	The API lacks the permission this method requires.	Grant it in Web Admin → Settings → API. Each method page lists the permission it needs.
`100011`	The API is not an admin in this chat.	Add the bot as admin, or use a method that does not require it.
`199990`	Operation is not permitted.	The action is blocked for this account or chat type.

Messages

Related to Message and Media.

Code	Meaning	What to do
`500001`	No message type.	Set the field matching the type you are sending.
`500003`	No message.	The payload had no content.
`500004`	Message is too long.	Text over ~1800 characters is converted to a `text_file`; send it as a document instead.
`500007`	Attachment not found.	The media id is wrong or expired. Re-upload — see Uploading Media Files.
`500008`	Invalid message type.	The `type` is not one the server recognises.
`500010`	Caption is too long.	Captions cap at 256 characters.
`500012`	No reference.	Every send needs a `reference`.
`500013`	No text message.	`sendText` was called without `text`.
`500040`	The API is not a member of the chat.	Add the bot to the chat first.

Signup filtering

Related to SIGNUP MANAGEMENT. The pattern codes are shared by both lists.

Code	Meaning	What to do
`500089`	Invalid whitelist or blacklist pattern.	The pattern is not a valid expression.
`500090`	Pattern is not matching.	The pattern did not match the identity it was applied to.
`188889`	User is not whitelisted.	Add them with addToWhitelist, or through a matching pattern.
`188888`	Blacklisted user.	Remove them with removeFromBlacklist. Remember the blacklist outranks the whitelist.

Menus

Related to MENUS.

Code	Meaning	What to do
`530000`	No menu provided.	Send at least one menu in the request.
`530001`	Missing `menu_ref` or `menu_id`.	Every menu needs one of the two.
`530002`	Missing `row_id`.	Every row needs one.
`530003`	Missing `callback` or `cell_id`, or an invalid `form` / `type`.	Check the cell against Cell.
`530004`	Missing the cell's `option`, or its `value` is missing `id` / `value`.	Selection cells need their options defined.

Session

Code	Meaning	What to do
`199999`	Syntax error, missing required parameter, or an unclassified failure.	The socket has closed. Reconnect and re-authenticate.
`199997`	No ID.	The socket has closed. Reconnect and re-authenticate.
`199992`	Another instance of this API is already running.	Only one instance may hold a session. Shut the other one down.