Ошибки API v2

Каждая ошибка API v2 приходит с настоящим кодом состояния HTTP и в одном и том же формате JSON. На этой странице перечислены все значения code, что они означают и что делать. Каждый ответ с ошибкой ссылается в docs на свой код на этой странице.

Объект ошибки#

{
  "error": {
    "code": "not_cancellable",
    "message": "Only a waiting message can be cancelled.",
    "field": null,
    "docs": "https://wbiztool.com/docs/api/v2/errors/#not_cancellable",
    "request_id": "req_4f1c2a9b8e7d6c5b4a392817",
    "status": "sent"
  }
}

Некоторые коды добавляют собственные подробности, например status, count, used или limit; они указаны у кода. Ответ с HTTP 401 также содержит заголовок WWW-Authenticate: Bearer realm="wbiztool", а ответы с 429 (и 409 idempotency_in_progress) — Retry-After.

Коротко: 4xx означает, что запрос нужно изменить (или, для 409 и 429, подождать); повтор без изменений даст тот же ответ. 5xx означает проблему на нашей стороне; повторите позже с тем же Idempotency-Key.

Аутентификация и лимиты#

api_v2_not_enabled#

HTTP 403. API v2 недоступен для этого рабочего пространства. Если вы видите эту ошибку, свяжитесь с нами.

Что делать: пока продолжайте пользоваться API v1. Карточка API-ключи v2 на странице Настройки → API-ключи покажет, когда он станет доступен вам.

missing_api_key#

HTTP 401. В запросе нет заголовка Authorization: Bearer …, либо он пуст или использует другую схему.

Что делать: передавайте Authorization: Bearer wbz_live_… (или wbz_test_…) в каждом запросе. См. Ключи.

invalid_api_key#

HTTP 401. Ключ не является ключом WbizTool v2: опечатка, обрезан или создан не нами.

Что делать: скопируйте ключ ещё раз, без пробелов и кавычек. После создания ключ нельзя показать снова; если вы его потеряли, создайте новый на странице Настройки → API-ключи.

v1_key_on_v2#

HTTP 401. Это ключ API v1 (40 символов: цифры и буквы от a до f). Ключи v1 работают только с /api/v1/.

Что делать: создайте ключ v2 в карточке API-ключи v2 на странице Настройки → API-ключи или вызывайте API v1.

api_key_revoked#

HTTP 401. Ключ был отозван на странице «Настройки → API-ключи», либо его рабочее пространство удалено или отключено.

Что делать: используйте другой ключ или попросите владельца рабочего пространства создать новый.

api_key_expired#

HTTP 401. Срок действия ключа истёк.

Что делать: попросите владельца рабочего пространства создать новый ключ и замените старый в своём приложении.

too_many_auth_failures#

HTTP 429. Больше 30 запросов за минуту с вашего IP-адреса пришли с неверным ключом. Retry-After равен 60.

Что делать: остановитесь и исправьте ключ в своём приложении, затем попробуйте снова через минуту.

demo_account#

HTTP 403. Демо-пространство не может пользоваться API.

Что делать: зарегистрируйте собственный аккаунт и создайте ключ там.

missing_scope#

HTTP 403. У ключа нет области доступа, которая нужна этому запросу. required_scope в ошибке говорит какая, например messages:send.

Что делать: создайте ключ с этой областью доступа (добавить области к существующему ключу нельзя). См. Области доступа.

rate_limited#

HTTP 429. Ключ сделал больше 60 запросов за эту минуту или больше 10 000 за сегодня (UTC).

Что делать: подождите столько секунд, сколько указано в Retry-After, и попробуйте снова. Распределяйте запросы во времени, используйте POST /messages/batch для многих получателей и вебхуки вместо опроса. См. Лимиты запросов.

Запрос#

not_found#

HTTP 404. По этому адресу ничего нет: в пути опечатка, или это не путь API v2.

Что делать: сверьте путь со справочником, например /api/v2/messages, а не /api/v2/message.

invalid_json#

HTTP 400. Тело запроса — некорректный JSON, часто из-за лишней запятой в конце или неэкранированного переноса строки в text.

Что делать: проверьте JSON и пишите переносы строк внутри строк как \n. Пусть тело собирает ваша HTTP-библиотека (json= в Python requests, JSON.stringify в JavaScript).

unsupported_content_type#

HTTP 415. Тело отправлено не так, как его принимает этот endpoint: все endpoint принимают application/json, кроме POST /media, который принимает multipart/form-data.

Что делать: укажите Content-Type: application/json и отправляйте JSON, либо отправляйте загрузку как multipart с полем file.

method_not_allowed#

HTTP 405. Путь существует, но не с этим методом, например PUT /messages/9817263.

Что делать: используйте метод, указанный в справочнике. Изменение напоминания — это PATCH, отмена сообщения — DELETE.

request_too_large#

HTTP 413. Тело запроса слишком большое.

Что делать: отправляйте меньше за один запрос, например разделите длинный список на несколько пакетов.

validation_failed#

HTTP 400. Запрос имеет неправильную структуру: отсутствует обязательное поле, значение имеет неверный тип или слишком длинное, поле неизвестно или limit не от 1 до 100. field называет первую проблему, а message объясняет её; errors перечисляет остальные.

Что делать: исправьте поле, указанное в field. Имена полей пишутся в snake_case, а неизвестные поля отклоняются, поэтому проверьте опечатки вроде txt или phone_number.

invalid_cursor#

HTTP 400. cursor повреждён или создан для других фильтров, чем в этом запросе.

Что делать: передавайте ровно тот next_cursor, который получили, с теми же фильтрами, что и для первой страницы. Чтобы изменить фильтры, начните заново без курсора.

invalid_idempotency_key#

HTTP 400. Заголовок Idempotency-Key пуст, длиннее 255 символов или содержит непечатаемые символы.

Что делать: используйте UUID или другую короткую строку из букв, цифр и дефисов.

idempotency_key_reused#

HTTP 422. Этот Idempotency-Key уже использовался за последние 24 часа с другим запросом: другим методом, путём или телом.

Что делать: используйте новый ключ для каждого нового запроса и повторно — только для повтора точно такого же запроса. См. Idempotency-Key.

idempotency_in_progress#

HTTP 409. Первый запрос с этим Idempotency-Key ещё обрабатывается. Retry-After равен 1.

Что делать: подождите секунду и отправьте тот же запрос снова: вы получите ответ на первый запрос.

internal_error#

HTTP 500. Что-то пошло не так на нашей стороне. Мы получаем об этом уведомление.

Что делать: повторите позже с тем же Idempotency-Key, чтобы работа не была выполнена дважды. Если это повторяется, свяжитесь с нами и укажите request_id.

Сообщения#

text_required#

HTTP 400. В сообщении нет ни text, ни media, или текст состоит только из пробелов. Для напоминания text обязателен.

Что делать: передайте text, media или оба.

text_too_long#

HTTP 400. text длиннее 3000 символов.

Что делать: сократите его или разделите на несколько сообщений.

too_many_recipients#

HTTP 400. В пакете больше 1000 получателей в to.

Что делать: разделите список на пакеты до 1000 получателей, каждый со своим Idempotency-Key.

invalid_datetime#

HTTP 400. Время (send_at, expires_at, since, until) указано не в ISO 8601 со смещением.

Что делать: пишите его так: 2026-10-20T09:30:00+05:30 или 2026-10-20T04:00:00Z. Время без смещения, например 2026-10-20 09:30, отклоняется, потому что оно неоднозначно. В строке запроса пишите + как %2B.

invalid_phone#

HTTP 422. Номер телефона (to.phone или phone при подключении номера) — не действительный номер в международном формате с +.

Что делать: пишите его с + и кодом страны, например +919876543210. Пробелы и дефисы допустимы, а 0 в начале вместо кода страны — нет.

invalid_username#

HTTP 422. to.username — не имя пользователя Telegram.

Что делать: пишите @name, ссылку t.me/name или tg: и ID пользователя. См. Получатели.

username_needs_telegram#

HTTP 422. Писать на имя пользователя Telegram можно только с аккаунта Telegram, а from — номер WhatsApp (или, без from, подключён не ровно один аккаунт Telegram).

Что делать: укажите в from ID аккаунта Telegram или отправляйте на номер телефона.

contact_not_found#

HTTP 422. В рабочем пространстве нет контакта с этим to.contact_id.

Что делать: проверьте ID (например, contact_id более раннего сообщения) или отправляйте на to.phone.

media_not_found#

HTTP 422 при отправке сообщения или создании напоминания с media.media_id; HTTP 404 для GET или DELETE /media/{id}. В Медиакаталоге рабочего пространства нет файла с этим ID, или он удалён.

Что делать: проверьте ID через Список файлов или загрузите файл снова.

invalid_media_url#

HTTP 422. media.url — не публичная ссылка http или https: она некорректна или ведёт на частный или локальный адрес.

Что делать: используйте ссылку, которую может открыть любой в интернете, или загрузите файл и отправляйте его по media_id.

time_in_past#

HTTP 422. send_at или expires_at уже прошло.

Что делать: проверьте время и его смещение. Чтобы отправить сейчас, не указывайте send_at.

number_not_found#

HTTP 422, если from (или number_id при подключении) — не номер этого рабочего пространства; HTTP 404 для GET /numbers/{id}, а также если ключу нельзя использовать этот номер.

Что делать: возьмите правильный id из Списка номеров.

from_required#

HTTP 422. from не указан, а в рабочем пространстве нет подключённых номеров или их больше одного, поэтому непонятно, с какого отправлять. (Для ключа, ограниченного некоторыми номерами: единственный подключённый номер не входит в его номера.)

Что делать: передайте from с id номера, с которого нужно отправить.

number_not_allowed#

HTTP 403. Ключ ограничен некоторыми номерами, а этому запросу нужен другой: from — другой номер, напоминание не указывает один из его номеров, запрос на подключение добавляет номер или указывает другой, либо запрос управляет webhook endpoint.

Что делать: используйте один из номеров ключа (number_ids в GET /me) или ключ без ограничения.

no_credits#

HTTP 402. У рабочего пространства закончились сообщения по тарифу. Для пакета requested и remaining показывают, сколько запрошено и сколько осталось.

Что делать: отправьте меньше сообщений или купите тариф либо дополнительные сообщения; платные тарифы дают безлимитные сообщения. См. Когда закончились сообщения.

account_disabled#

HTTP 403. Аккаунт владельца рабочего пространства отключён, поэтому рабочее пространство не может отправлять сообщения.

Что делать: свяжитесь с поддержкой.

number_daily_cap_reached#

HTTP 429. Номер-отправитель отправил 1000 сообщений за последние 24 часа (честное использование), или пакет не умещается в оставшийся запас: requested и room показывают сколько.

Что делать: отправьте остальное позже или с другого номера.

message_rejected#

HTTP 422. Сообщение не удалось поставить в очередь; причина — в message. Ничего не сохранено.

Что делать: исправьте то, что описано в message, и отправьте снова.

message_not_found#

HTTP 404. Для этого ключа нет сообщения с таким ID: его не существует, оно принадлежит другому рабочему пространству или отправлено с номера, который ключу использовать нельзя. Тестовый ключ видит только свои тестовые сообщения, а рабочий ключ никогда их не видит.

Что делать: проверьте ID и то, что вы используете ключ того же типа (рабочий или тестовый), которым было создано сообщение.

not_cancellable#

HTTP 409. Отменить можно только ожидающее сообщение (queued или scheduled), а это уже не ожидает. status в ошибке показывает, в каком оно состоянии сейчас, например sent или cancelled.

Что делать: отменять нечего. Отправленное сообщение отозвать нельзя.

Напоминания#

invalid_cron#

HTTP 400. schedule.cron — не выражение cron из 5 частей или описывает время, которое никогда не наступит (например, 31 февраля).

Что делать: укажите минуту, час, день месяца, месяц и день недели, например 0 9 * * 1 для понедельников в 09:00. См. Расписание.

invalid_timezone#

HTTP 400. schedule.timezone — не название часового пояса IANA.

Что делать: используйте название вроде Asia/Kolkata, Europe/London или America/New_York, а не сокращение вроде IST или смещение вроде +05:30. См. справочник часовых поясов.

number_not_connected#

HTTP 422. from напоминания — не подключённый номер этого рабочего пространства.

Что делать: сначала подключите номер, выберите подключённый или не указывайте from (null), чтобы отправлял любой подключённый номер.

reminder_not_found#

HTTP 404. Нет напоминания с таким ID: его не существует, оно удалено или отправляется с номера, который ключу использовать нельзя.

Что делать: проверьте ID через Список напоминаний.

Медиафайлы#

file_too_large#

HTTP 413. Загруженный файл больше 64 МБ.

Что делать: сожмите или разделите его; для видео уменьшите разрешение.

unsupported_file_type#

HTTP 415. Файл такого типа нельзя отправить в WhatsApp. Тип определяется по расширению в конце имени файла.

Что делать: проверьте типы, которые можно загрузить, и сохраняйте расширение в имени (price-list.pdf, а не price-list).

storage_full#

HTTP 422. Файл не помещается в Медиакаталог рабочего пространства по его тарифу. used и limit показывают, сколько занято и сколько разрешено, в байтах.

Что делать: удалите файлы, которые больше не нужны, или перейдите на тариф с большим хранилищем.

media_in_use#

HTTP 409. Файл пока нельзя удалить: что-то ещё будет его отправлять (ожидающее сообщение, в том числе из кампании, активное напоминание или активный триггер Google Sheets). count показывает, сколько таких.

Что делать: сначала отмените или измените их либо дождитесь, пока ожидающие сообщения уйдут.

upload_failed#

HTTP 502. Файл не удалось сохранить на нашей стороне.

Что делать: попробуйте снова с тем же Idempotency-Key.

Проверки номеров#

no_valid_numbers#

HTTP 422. Ни один элемент в numbers не является номером телефона. skipped показывает, сколько было элементов.

Что делать: передавайте номера в международном формате с +, по одному в элементе, например +919876543210.

too_many_numbers#

HTTP 422. В проверке больше номеров, чем может быть в одной проверке: больше 10 000 элементов в запросе или больше номеров, чем тариф позволяет на одну проверку. count и limit показывают сколько.

Что делать: разделите список на несколько проверок. См. Лимиты тарифа.

number_check_quota_reached#

HTTP 422. Проверка превысила бы лимит проверок номеров тарифа за этот расчётный период. requested, used и limit показывают сколько.

Что делать: проверьте меньше номеров, дождитесь следующего расчётного периода или перейдите на тариф выше.

number_check_not_found#

HTTP 404. В рабочем пространстве нет проверки номеров с таким ID.

Что делать: проверьте ID через Список проверок.

Номера#

plan_required#

HTTP 403. Тариф рабочего пространства не включает то, что нужно этому запросу: API QR-кода для подключения номера, напоминания для создания, изменения или возобновления напоминания или проверку номеров для запуска проверки номеров.

Что делать: владелец может перейти на тариф выше на странице Цены. Чтение того, что уже есть, работает на любом тарифе.

number_limit_reached#

HTTP 403. В тарифе нет места для ещё одного номера.

Что делать: переподключите существующий номер через number_id, удалите номер, которым больше не пользуетесь, или перейдите на тариф выше.

already_connected#

HTTP 409. Номер уже подключён.

Что делать: ничего делать не нужно: с него можно отправлять. Проверьте через Получение номера.

connect_in_progress#

HTTP 409. Этот номер подключается прямо сейчас. number_id в ошибке показывает какой.

Что делать: опрашивайте GET /numbers/{id} для этого номера, а не запрашивайте подключение снова. Через 10 минут без сканирования можно запросить снова.

Вебхуки#

invalid_webhook_url#

HTTP 422. url — не публичный адрес https://: это http://, некорректный адрес или адрес, ведущий на частный или локальный хост.

Что делать: используйте адрес https://, на котором ваш сервер отвечает из интернета. Для тестирования на своём компьютере используйте сервис туннелей, который даёт публичный адрес https://.

webhook_limit_reached#

HTTP 403. В рабочем пространстве уже 5 webhook endpoint.

Что делать: удалите тот, которым больше не пользуетесь. Один endpoint может получать события всех типов.

webhook_not_found#

HTTP 404. Нет webhook endpoint с таким ID: его не существует, или он удалён. Тестирование или замена секрета у переставшего работать endpoint тоже возвращает эту ошибку; при чтении он показывается с active: false.

Что делать: проверьте ID через Список endpoint. Если он перестал работать, добавьте его снова.

Тестовый режим#

test_mode_unsupported#

HTTP 403. Тестовый ключ (wbz_test_…) может отправлять, читать и отменять тестовые сообщения и читать остальные данные рабочего пространства, но не может изменять ничего другого: подключать номер, создавать, изменять или удалять напоминания, загружать или удалять медиафайлы, запускать проверку номеров или управлять webhook endpoint. Фильтр status в GET /messages для тестовых ключей тоже не поддерживается.

Что делать: используйте для этих запросов рабочий ключ (wbz_live_…). См. Тестовый режим.