Ошибки, n8n и ограничения
Ошибки приходят единым конвертом { error, description, data }. Основные коды:
- channel_not_found (404) — нет такого channel_id (или он не ваш, не выбран для ключа, или отключён).
- not_found (404) — нет такой отправки, подписки или доставки.
- forbidden (403) — у ключа нет права на это действие (см. «Права ключа»).
- line_license_expired (402) — срок лицензии линии закончился; продлите линию.
- idempotency_conflict (409) — client_msg_id уже использован для другой отправки.
- replay_unavailable (409) — повторить можно только неудавшуюся доставку с действующим доступом.
- outside_24h_window (422) — окно 24 часов закрыто, обычный текст не уйдёт (шлите шаблоном).
- invalid_message (422) — канал отклонил содержимое, шаблон не найден или не APPROVED, note / voice не подходят к типу файла, либо chat_type / reply_to противоречат каналу или диалогу.
- template_error (422) — Meta отклонила создание или правку шаблона; причина в description, коды в data.
- invalid_request (400) — тело, параметры или заголовок не прошли валидацию (в том числе media_url не из POST /media/ и нет Idempotency-Key); подробности по полям в data.fields.
- invalid_webhook_url (400) — URL не https либо приватный адрес.
- storage_quota_exceeded (413) — исчерпана квота хранилища файлов.
- unauthorized (401) — ключ не передан, испорчен или отозван.
- rate_limited (429) — превышен лимит частоты; сколько ждать, в data.retry_after_seconds и в заголовке Retry-After.
- method_not_allowed (405) — метод не поддерживается этим адресом.
- internal_error (500) — сбой на нашей стороне; повтор безопасен, отправка с тем же client_msg_id не задвоится.
Лимиты частоты считаются в минуту, скользящим окном, отдельно по видам запросов. Ниже — значения по умолчанию; для вашего проекта их могут поднять.
| Вид запросов | На ключ | На все ключи тенанта |
|---|---|---|
| Чтение: линии, история, шаблоны, /allowed/, итог отправки | 1200 | 6000 |
| Отправка: POST /messages/ | 600 | 3000 |
| Обращения к провайдеру: POST /media/, создание, правка и удаление шаблонов, здоровье шаблона | 60 | 300 |
| Управление: вебхук, смена секрета, подписки, добор и повтор доставок | 30 | 150 |
Свой бюджет у каждого ключа, а общий потолок тенанта не даёт умножить пропускную способность новыми ключами. Проверка здоровья шаблона идёт не больше двух одновременно на ключ. При превышении приходит 429 в том же конверте плюс заголовок Retry-After — уважайте его, а не ретрайте вслепую.
n8n. Готовой ноды пока нет, но интеграция собирается из коробочных: нода Webhook принимает входящие (включите raw / binary body, иначе не проверить HMAC), нода HTTP Request шлёт ответы с заголовком Authorization: Bearer.
- Webhook-нода: включите raw / binary body, сверяйте X-Wahub-Signature-V2 по сырому телу.
- HTTP Request-нода: POST на /messages/ с заголовком Authorization: Bearer gw_…
Ограничения, которые стоит учесть при проектировании интеграции:
- Создание шаблонов через Gateway API: только текстовые header/body/footer — без кнопок и медиа-заголовков.
- Нет эксклюзива и handoff: бот и живой оператор могут ответить одновременно (двойные ответы).
- На один канал может быть подписано несколько потребителей — событие получат все.
- Медиа отдаётся путём на нашем хосте и требует того же ключа, публичной ссылки нет.