Ошибки интеграций и API
При работе с узлами интеграций (HTTP-запросы, приложения, вебхуки) внешний сервис или API может вернуть ответ с кодом ошибки. Ниже — типовые коды в диапазоне 4xx (ошибка запроса или авторизации) и 5xx (ошибка на стороне сервера). Точный текст сообщения зависит от сервиса; в логах узла обычно виден код и тело ответа.
4xx — ошибки клиента (запрос или доступ)
400 Bad Request
Что значит: сервер не принял запрос из-за некорректного формата или данных (неверный JSON, обязательное поле пропущено, неверный тип значения).
Что делать
Проверьте тело запроса, заголовки и параметры в настройках узла. Сверьтесь с документацией API сервиса — какие поля обязательны и в каком формате.
401 Unauthorized
Что значит: запрос не авторизован. Токен отсутствует, истёк или неверный.
Что делать
Проверьте настройки авторизации узла (API-ключ, Bearer-токен, OAuth). Обновите токен или заново пройдите авторизацию в разделе Авторизации.
403 Forbidden
Что значит: доступ к ресурсу запрещён. Авторизация может быть успешной, но прав на выполнение действия нет (нет доступа к объекту, лимиты приложения, блокировка по IP и т.п.).
Что делать
Проверьте права аккаунта/приложения в самом сервисе; убедитесь, что токен имеет нужные scope (разрешения). При необходимости создайте новую авторизацию с расширенными правами.
404 Not Found
Что значит: ресурс по указанному URL не найден (страница, объект, метод API удалён или путь набран неверно).
Что делать
Проверьте URL в настройках узла (опечатка, версия API, правильный путь к объекту). Убедитесь, что ресурс существует в сервисе и не был удалён.
408 Request Timeout
Что значит: сервер не дождался завершения запроса в отведённое время и разорвал соединение.
Что делать
Увеличьте таймаут в настройках узла (если доступен); упростите или сократите объём запроса; проверьте, не перегружен ли внешний сервис.
429 Too Many Requests
Что значит: превышен лимит запросов к API (rate limit). Сервис временно отклоняет запросы, чтобы снизить нагрузку.
Что делать
Снизьте частоту запусков сценария или количество запросов к одному API; добавьте задержки между запросами или используйте пагинацию. Для лимитов самой платформы см. Ошибки платформы и лимитов.
5xx — ошибки сервера (внешний сервис)
500 Internal Server Error
Что значит: на стороне внешнего сервиса произошла внутренняя ошибка. Запрос мог быть корректным, но сервер не смог его обработать.
Что делать
Повторите запрос позже; проверьте статус сервиса (status-страница провайдера). Если ошибка воспроизводится — обратитесь в поддержку сервиса или добавьте в сценарий повтор при ошибке.
502 Bad Gateway
Что значит: сервер (или прокси) выступал как шлюз и получил недействительный ответ от вышестоящего сервера. Часто при перегрузке или сбое бэкенда сервиса.
Что делать
Повторите запрос через некоторое время; при устойчивой ошибке — проблема на стороне внешнего сервиса.
503 Service Unavailable
Что значит: сервис временно недоступен (техработы, перегрузка, отказ узла). Обычно просят повторить позже.
Что делать
Повторите выполнение сценария позже; включите повтор при ошибке в настройках узла или сценария.
504 Gateway Timeout
Что значит: сервер (шлюз) не дождался ответа от вышестоящего сервера в отведённое время. Запрос «завис» на стороне внешнего сервиса.
Что делать
Повторите запрос; при повторяющихся 504 — проблема или лимиты на стороне внешнего API (увеличить таймаут у них или уменьшить объём запроса).