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

{
  "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.