Коды ошибок вебхуков (mpbx-webhooks)
Возвращаются маршрутами исходящих вебхуков под /api/v1/webhooks (W7-API-02). Сообщения никогда не содержат
секрет подписи, подпись или ответ получателя; в них указываются не более чем идентификаторы, имена полей
и правила. Руководство: Исходящие вебхуки.
| Код | HTTP | Значение | Что делать |
|---|---|---|---|
MPBX-WEBHOOK-NOT-FOUND | 404 | В этой компании нет такой конечной точки (конечная точка другой компании не видна). | Проверьте идентификатор. |
MPBX-WEBHOOK-DELIVERY-NOT-FOUND | 404 | В этой компании нет такой доставки либо она была удалена (доставленные хранятся 7 дней, недоставленные 30 дней). | Проверьте идентификатор. |
MPBX-WEBHOOK-URL-INVALID | 400 | URL пуст, длиннее 2048 символов, не является URL либо содержит пробелы, управляющие символы или фрагмент. | Укажите обычный адрес https://host[:port]/path?query. |
MPBX-WEBHOOK-URL-BLOCKED | 400 | URL не разрешён: не https, содержит данные пользователя, порт ниже 1024 (кроме 443), либо адрес частный, loopback, link-local (метаданные облака), carrier-grade NAT, документационный, многоадресный или зарезервированный (включая формы IPv4-mapped и NAT64), либо внутреннее имя (localhost, *.local, *.internal, однокомпонентное имя). Та же проверка повторяется при каждой доставке после разрешения имени. | Используйте публичный адрес https. |
MPBX-WEBHOOK-EVENT-TYPE-UNKNOWN | 400 | Запись event_types не является типом события или шаблоном topic.*, на который можно подписаться (audit.* и webhook.test недоступны никогда), либо требует права на события, которого у вас нет на уровне компании (messaging:read для sms.*, call_history:read для cdr.written и т. д.; см. «Кто что получает» в руководстве по вебхукам). Также возникает при изменении URL конечной точки, фильтр которой называет такие события. | Используйте GET /api/v1/webhooks/event-types, который перечисляет только то, что вы можете получать, либо попросите того, у кого есть право. |
MPBX-WEBHOOK-NAME-TAKEN | 409 | Другая конечная точка компании имеет такое название. | Выберите другое название. |
MPBX-WEBHOOK-FIELD-INVALID | 400 | Поле вне диапазона: name (от 1 до 80 символов), rate_per_minute (от 1 до 6000), grace_period_seconds (от 0 до 604800) или больше 64 записей фильтра. | Исправьте указанное поле. |
MPBX-WEBHOOK-CHANGED | 409 | Конечная точка изменилась между вашим чтением и записью. | Прочитайте её заново и повторите запрос с новым ETag. |
MPBX-WEBHOOK-LIMIT-REACHED | 409 | В компании уже 20 конечных точек. | Удалите одну или передайте больше типов событий одной конечной точке. |
MPBX-WEBHOOK-RATE-LIMITED | 429 | Более 10 тестовых доставок и повторных отправок в минуту для компании. | Подождите минуту (Retry-After: 60). |
MPBX-WEBHOOK-SECRET-UNREADABLE | 500 | Защищённый секрет подписи конечной точки не открывается (мастер-ключ заменили без повторной упаковки или строка повреждена). Доставки на неё не работают. | Перевыпустите секрет (POST /webhooks/{id}/rotate-secret) и передайте новый получателю. |
MPBX-WEBHOOK-NOT-REDELIVERABLE | 409 | Доставка ещё ожидает (попытки или повтора); повторно отправить можно только доставленную или недоставленную доставку. | Дождитесь её завершения или посмотрите её попытки. |
MPBX-WEBHOOK-LOG-UNAVAILABLE | 503 | Журнал попыток требует ClickHouse, которого нет в этой установке, либо строку журнала не удалось прочитать. Доставки продолжают работать; не хватает только истории. | Настройте clickhouse.url. |
MPBX-WEBHOOK-ENDPOINT-DISABLED | 409 | Тест запрошен для конечной точки, которая выключена. | Сначала включите её (PATCH с enabled: true). |
Коды ошибок доставки
Неудачная попытка сохраняет короткий машинный код как last_error доставки (и в журнале попыток). Это
никогда не текст от получателя.
last_error | Значение | Повторяется |
|---|---|---|
http_status | Получатель ответил статусом вне 2xx (см. last_status). Ответ 3xx считается неудачей: перенаправления никогда не выполняются. Retry-After (секунды, не более одного часа) увеличивает ожидание. | да |
timeout | Ответа нет за 10 секунд (подключение за 5). | да |
network | Соединение или рукопожатие TLS не удалось либо оборвалось. | да |
dns | Имя хоста не разрешилось. | да |
blocked | Адрес назначения разрешился в адрес, который не разрешён (см. MPBX-WEBHOOK-URL-BLOCKED). | нет: сразу недоставлено |
too_large | Тело больше 256 КиБ. | нет: сразу недоставлено |
rate_limit | Не ошибка: лимит rate_per_minute конечной точки исчерпан, доставка ждёт несколько секунд (записывается как deferred, попытка не засчитывается). | неприменимо |