Ошибки вебхуков Discord: 400, 401, 403, 404, 429 — причины и решения

Вебхук Discord не работает? Начните отсюда

Когда вебхук падает, Discord возвращает HTTP-код статуса и, как правило, JSON-тело с полями code и message. Эти два поля точно говорят, что не так. Здесь разобраны все статусы, которые реально встречаются, их причины и способы исправить.

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

curl -i -H "Content-Type: application/json" \
     -d '{"content": "test"}' \
     "https://discord.com/api/webhooks/ID/TOKEN"

204 No Content или 200 OK → вебхук работает.
Что-то другое → сопоставьте код с разделами ниже.

400 — Bad Request (Invalid Form Body)

Самая частая ошибка. Ваш JSON некорректен или нарушает правило Discord. Тело обычно выглядит так:

{ "message": "Invalid Form Body", "code": 50035, "errors": { ... } }

Причины и решения:

Сломанный JSON — висячая запятая, одинарные кавычки вместо двойных или неэкранированная кавычка. Сначала проверьте payload в JSON-линтере.
Пустое сообщение — нужно отправить хотя бы одно из content, embeds или files. Пустой {} отклоняется с кодом 50006.
content длиннее 2000 символов — разбейте сообщение или перенесите текст в описание embed.
Превышены лимиты embed — заголовок ≤ 256, описание ≤ 4096, максимум 25 полей и 6000 символов суммарно по всем embed. См. шпаргалку по лимитам embed.
color как hex-строка — Discord ждёт десятичное число (5763719), а не "#57F287". См. цвета embed.
Неверный Content-Type — отправляйте application/json (или multipart/form-data при загрузке файлов).

Объект errors указывает на конкретное поле — читайте его внимательно, он называет проблемный ключ.

401 — Unauthorized (Invalid Webhook Token)

{ "message": "Invalid Webhook Token", "code": 50027 }

Токен в URL вебхука неверный или больше не валиден. Это бывает, когда:

Токен вебхука пересоздан в Discord (Изменить вебхук → URL изменился). Старые URL мгновенно перестают работать.
Вы скопировали URL не полностью или обрезали токен.
Вы случайно отправили заголовок Authorization — вебхуки аутентифицируются токеном в URL, поэтому добавление bearer/bot-токена вызывает конфликт. Не отправляйте его.

Решение: откройте вебхук в Настройки сервера → Интеграции → Вебхуки, нажмите Копировать URL вебхука и используйте свежий полный URL.

403 — Forbidden

{ "message": "Missing Permissions", "code": 50013 }

Запрос дошёл до Discord, но не разрешён. Частые причины:

Блокировка IP — Discord блокирует некоторые диапазоны IP хостингов/дата-центров (в частности, серверы Roblox). Код работает локально, но падает на сервере. Пускайте через прокси — см. отправку вебхуков из Roblox.
Попытка упомянуть @everyone без прав или пинг в канале, где у вебхука нет прав.
Публикация в тред, к которому у вебхука нет доступа, или в форум-канал без thread_name. См. треды и форумы.

404 — Unknown Webhook

{ "message": "Unknown Webhook", "code": 10015 }

Вебхук больше не существует. В отличие от 401, это навсегда — токен исправить нечем. Бывает, когда:

Вебхук удалили в Discord.
Удалили канал, что убирает его вебхуки.
В ID вебхука опечатка (числовая часть URL).

Решение: создайте новый вебхук и обновите URL в приложении.

429 — Too Many Requests (рейт-лимит)

{ "message": "You are being rate limited.", "retry_after": 1.5, "global": false }

Вы превысили лимит вебхука — примерно 30 запросов в минуту на один вебхук. В ответе есть retry_after (сколько секунд ждать) и заголовки X-RateLimit-*.

Решения:

Уважайте retry_after — подождите указанное число секунд и повторите. Никогда не долбите в плотном цикле.
Группируйте сообщения — объединяйте много обновлений в один payload вместо отдельного запроса на каждое.
Распределяйте нагрузку — отправляйте разные типы событий в разные вебхуки в разных каналах.

Полные стратегии — в гайде по лимитам.

Другие коды статуса

Код	Значение	Решение
`405 Method Not Allowed`	Неверный HTTP-метод	`POST` для отправки, `PATCH`/`DELETE` для правки/удаления
`413 Payload Too Large`	Файл больше лимита загрузки	Бесплатные вебхуки разрешают 10 МБ на запрос — сожмите или разбейте
`500` / `502` / `503`	Сбой на стороне Discord	Временно — повторите с backoff; проверьте статус Discord

Краткая таблица

Статус	Код Discord	Причина одной строкой	Решение
400	50035 / 50006	Некорректный JSON или превышены лимиты	Проверьте JSON и лимиты embed
401	50027	Невалидный/пересозданный токен	Скопируйте свежий URL вебхука
403	50013	Блок IP или нет прав	Используйте прокси / исправьте права
404	10015	Вебхук или канал удалён	Создайте новый вебхук
429	—	Рейт-лимит	Уважайте `retry_after`, группируйте

Как избежать ошибок до отправки

Самый быстрый способ полностью избежать 400 — собрать и проверить payload визуально. Бесплатный конструктор вебхуков следит за каждым лимитом по мере ввода и генерирует гарантированно валидный JSON, который заработает с первого раза. Для программной отправки логируйте полное тело ответа — поля message и code от Discord почти всегда называют точную проблему.