Обработка ошибок API

Коротко: платформа возвращает HTTP-коды. Формат тела ошибки отличается в зависимости от API: OMNI API использует один формат, Broadcasts API и Recipients API — другой.

Кому подходит

• Роль: Разработчик
• Уровень: Опытный

HTTP-коды

Формат ошибки OMNI API

Используется в эндпоинтах /api/v1/messages, /api/v1/omnimessages, /api/v1/senders, /api/v1/channels, /api/v1/balance, /api/v1/edrs, /api/v1/templates, /api/v1/wa_templates.

Пример ответа с ошибкой:

{
  "error": true,
  "data": {
    "message": "something went wrong",
    "requestId": "af8c5065-5849-455b-ae1a-6a0b9f4b7209"
  }
}

Формат ошибки Broadcasts API и Recipients API

Используется в эндпоинтах /api/v1/broadcast/* и /api/v1/recipient/*.

Пример ответа с ошибкой:

{
  "execId": null,
  "key": "errors.common_error",
  "code": "ValidationError",
  "message": "Selected filter's attributes don't exist.",
  "args": null
}

Частые ошибки

400 Bad Request

Причины:

• Неверный формат JSON.
• Отсутствует обязательное поле (например, phoneNumber, type, contentType).
• Неверный формат номера телефона.
• Передан параметр, которого нет в фильтре.

Примеры сообщений:

• Phone number can't be null or empty
• Recipient type can't be null
• Selected filter's attributes don't exist.

Решение: проверьте тело запроса и обязательные поля.

401 Unauthorized

Причины:

• Заголовок X-API-Key не передан.
• Ключ неверный.
• Ключ от другого сервиса.

Решение: проверьте заголовок и ключ. Подробнее — Ошибка 401.

403 Forbidden

Причины:

• У ключа нет нужного scope.
• Scope отключён в настройках.

Решение: добавьте нужный scope в настройках ключа. Подробнее — API-ключи.

404 Not Found

Причины:

• Неверный URL.
• Несуществующий ID (шаблон, получатель, рассылка).

Решение: проверьте базовый URL и параметры.

500 Internal Server Error

Причины:

• Ошибка на стороне сервера.

Решение:

1. Повторите запрос через 30 секунд.
2. Сохраните requestId (для OMNI API) или execId (для Broadcasts/Recipients).
3. Обратитесь в поддержку.

Что приложить к обращению в поддержку

• Метод и URL запроса.
• Тело запроса (без API-ключа).
• Полный ответ с ошибкой.
• Код ответа.
• Время запроса.
• requestId или execId, если есть.

См. также

Нужна помощь?

• OTP-коды: support@otpcod.ru
• Multi API: support@multiapi.ru
• Мой диалог: support@mydialogi.ru