Documentation

Errors

One consistent error format and the codes you will see.

FormatLive

Native REST
{ "error": { "code": "not_found", "message": "Instance not found" } }

// validation errors add details
{ "error": { "code": "validation_error", "message": "Invalid request", "details": [{ "path": "name", "message": "Too small" }] } }

CodesLive

HTTPcodeMeaning
400validation_errorA field is missing or malformed
400invalid_chat_idThe chatId is not a valid number, group or LID
400mention_not_in_groupA mentioned person is not a member of the group
400invalid_idempotency_keyThe Idempotency-Key is longer than 128 characters
401unauthorizedNo valid API key or session, or a wrong idInstance or token
400invalid_bot_tokenTelegram or MAX rejected the bot token: nothing was stored
400bot_token_requiredThis Telegram or MAX instance needs a bot token to connect
400bot_token_not_applicableBot tokens are only for Telegram and MAX instances
403forbiddenYour role cannot do this
403missing_scopeThe API key lacks the scope this route needs
403api_key_not_allowedAPI keys cannot call account, support, notification, admin or key-management routes
403email_unverifiedConfirm your email first
404not_foundNo such resource in your workspace (also used for other workspaces, so existence is not revealed)
409instance_not_connectedThe instance is not connected: connect it and scan the QR code
413file_too_largeFiles are limited to 25 MB
415unsupported_file_typeThe file type is not allowed or does not match its content
422recipient_opted_outThe recipient opted out: sending is refused
422not_supported_on_channelThis channel cannot do that (for example polls on MAX): check /capabilities
422no_file / empty_fileNo file was provided, or it is empty
422file_fetch_failed / file_fetch_timeoutWe could not download the URL you gave
422not_editableOnly text messages you sent can be edited
422mentions_only_in_groupsMentions need a group chat
429daily_limit_reachedThe number reached its 24-hour sending cap
429rate_limitedToo many requests: slow down
501not_implementedA method that is deliberately not offered (see the API reference)
500internal_errorOur fault; retry, then contact support