Полный список кодов ошибок платформы и рекомендации по их обработке на стороне клиента.
Все ошибки API возвращаются в едином формате с машиночитаемым кодом и человекочитаемым сообщением:
{
"error": {
"code": "invalid_route",
"message": "Маршрут /v1/unknown не найден",
"request_id": "req_7f3a91"
}
}Указывайте request_id при обращении в поддержку — это ускоряет диагностику в 90% случаев.
| Код | Значение | Что делать |
|---|---|---|
400 | Некорректный запрос | Проверьте формат тела запроса и обязательные поля |
401 | Ключ недействителен или отсутствует | Проверьте заголовок Authorization и срок действия ключа |
403 | Недостаточно прав (scope) | Убедитесь, что ключу назначена нужная область действия |
404 | Маршрут или ресурс не найден | Проверьте конфигурацию маршрутов в проекте |
409 | Конфликт состояния ресурса | Например, повторное создание с тем же идемпотентным ключом |
422 | Запрос синтаксически корректен, но не проходит валидацию | Смотрите поле details в теле ответа |
429 | Превышен лимит запросов | См. раздел «Лимиты и квоты» |
502 | Upstream-сервис недоступен или вернул некорректный ответ | Проверьте доступность вашего сервиса за шлюзом |
504 | Upstream не ответил вовремя | Проверьте производительность бэкенда или увеличьте таймаут в конфигурации |
| Код | Описание |
|---|---|
invalid_route | Запрошенный путь не соответствует ни одному настроенному маршруту |
upstream_timeout | Ваш сервис не ответил в течение установленного таймаута |
signature_mismatch | Подпись вебхука не прошла проверку — вероятно, использован неверный секрет |
quota_exceeded | Исчерпан месячный лимит запросов тарифа |
invalid_config | Конфигурация hexly.config.yaml не прошла валидацию при деплое |