Errors
One consistent error format and the codes you will see.
FormatLive
{ "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
| HTTP | code | Meaning |
|---|---|---|
| 400 | validation_error | A field is missing or malformed |
| 400 | invalid_chat_id | The chatId is not a valid number, group or LID |
| 400 | mention_not_in_group | A mentioned person is not a member of the group |
| 400 | invalid_idempotency_key | The Idempotency-Key is longer than 128 characters |
| 401 | unauthorized | No valid API key or session, or a wrong idInstance or token |
| 400 | invalid_bot_token | Telegram or MAX rejected the bot token: nothing was stored |
| 400 | bot_token_required | This Telegram or MAX instance needs a bot token to connect |
| 400 | bot_token_not_applicable | Bot tokens are only for Telegram and MAX instances |
| 403 | forbidden | Your role cannot do this |
| 403 | missing_scope | The API key lacks the scope this route needs |
| 403 | api_key_not_allowed | API keys cannot call account, support, notification, admin or key-management routes |
| 403 | email_unverified | Confirm your email first |
| 404 | not_found | No such resource in your workspace (also used for other workspaces, so existence is not revealed) |
| 409 | instance_not_connected | The instance is not connected: connect it and scan the QR code |
| 413 | file_too_large | Files are limited to 25 MB |
| 415 | unsupported_file_type | The file type is not allowed or does not match its content |
| 422 | recipient_opted_out | The recipient opted out: sending is refused |
| 422 | not_supported_on_channel | This channel cannot do that (for example polls on MAX): check /capabilities |
| 422 | no_file / empty_file | No file was provided, or it is empty |
| 422 | file_fetch_failed / file_fetch_timeout | We could not download the URL you gave |
| 422 | not_editable | Only text messages you sent can be edited |
| 422 | mentions_only_in_groups | Mentions need a group chat |
| 429 | daily_limit_reached | The number reached its 24-hour sending cap |
| 429 | rate_limited | Too many requests: slow down |
| 501 | not_implemented | A method that is deliberately not offered (see the API reference) |
| 500 | internal_error | Our fault; retry, then contact support |