Notification Error Codes
Reference of error codes that can be delivered in the error_code field of webhook notifications (message.status, client.phone.changed, etc.). For each code the messenger where it may occur is indicated: Telegram, MAX, both, or «—» for errors not tied to a specific messenger.
Delivery
| Code | Description | Messenger |
|---|---|---|
| TOKEN_INVALID | The bot token is invalid or was revoked by the messenger. Check the token in bot settings. | Telegram · MAX |
| BAD_REQUEST | The messenger rejected the request due to invalid message parameters. | Telegram · MAX |
| RATE_LIMIT | Messenger rate limit exceeded. The message will be retried after a delay. | Telegram · MAX |
| WEBHOOK_CONFLICT | Telegram webhook conflict: another server has already set a webhook for this bot. | Telegram |
| NETWORK_ERROR | Network error while calling the messenger API (connection reset, unreachable). | Telegram · MAX |
| DNS_ERROR | Failed to resolve the messenger API hostname. | Telegram · MAX |
| SSL_ERROR | TLS/SSL error while establishing a secure connection to the messenger API. | Telegram · MAX |
| TIMEOUT | Timed out waiting for a response from the messenger API. | Telegram · MAX |
| CONNECTION_CLOSED | The connection to the messenger API was closed before a response was received. | Telegram · MAX |
| PROXY_ERROR | Proxy relay error (the intermediate delivery server is unavailable). | Telegram · MAX |
| CONFIG_MISSING | The messenger webhook URL is not configured in platform settings. | Telegram · MAX |
| DELIVERY_FAILED | Generic message delivery failure. The cause is unclassified or unknown. | Telegram · MAX |
Recipient
| Code | Description | Messenger |
|---|---|---|
| USER_BLOCKED_BOT | The recipient blocked the bot. Telegram: HTTP 403 «bot was blocked by the user»; MAX: chat.denied. Delivery is terminal (no retries). | Telegram · MAX |
| USER_NOT_FOUND | Recipient not found (not registered in the messenger). | Telegram · MAX |
| USER_INACTIVE | Recipient is inactive or unavailable in the messenger. | Telegram · MAX |
| DIALOG_SUSPENDED | Dialog suspended: MAX returned error.dialog.suspended (recipient blocked the bot or a moderator restriction applies). | MAX |
Phone change
| Code | Description | Messenger |
|---|---|---|
| PHONE_NEVER_EXISTED | The phone number has never been registered in any messenger. | — |
| PHONE_ALREADY_INACTIVE | The phone number is already inactive. | — |
| PHONE_MULTIPLE_CLIENTS | The phone number is linked to several different accounts. | — |
| PHONE_NOT_LINKED | The phone number is not linked to any account. | — |
| PHONE_NOT_IN_BOT | The new phone number has never been registered in any messenger. | — |
| PHONE_NOT_ACTIVE | The new phone number is inactive. | — |
| MIGRATION_SAME_CLIENT | The old and new phone numbers are already linked to the same account. | — |