SmengoAPI

Коды ошибок

Любая ошибка /api/v1 возвращается в едином формате — вне зависимости от эндпоинта и причины.

Формат ошибки

{
  "error": {
    "code": "missing_scope",
    "message": "The API key does not have the scope required by this endpoint.",
    "hint": "Request the employees.read scope for this key.",
    "docs_url": "https://smengo.com/api-docs/reference/errors#missing_scope",
    "request_id": "8f14e45f-9e05-4f1a-8a3e-3d2b1c0f9b1b"
  }
}
  • code — машиночитаемый код из каталога ниже; удобно ветвить логику интеграции по нему.
  • message — человекочитаемое описание на английском.
  • hint — опционально: что сделать, чтобы починить (например, какой скоуп запросить).
  • docs_url — прямая ссылка на описание этого кода на этой странице. Исключения — subscription_inactive и module_required: их docs_url ведёт на страницу биллинга в приложении Smengo (где проблема и чинится), а не сюда.
  • request_id — тот же uuid, что и в заголовке X-Request-Id ответа. Указывайте его, когда пишете в поддержку — по нему конкретный запрос находится в логах, без него разбор занимает дольше.

HTTP-статус ответа соответствует коду (см. таблицу в конце страницы). Ветвить можно и по статусу, и по error.code — но code надёжнее: он однозначно определяет причину, тогда как один HTTP-статус (например, 403) покрывает два разных кода.

Каталог кодов

unauthorized

HTTP-статус: 401.

Заголовок Authorization отсутствует, его формат битый, ключ неизвестен системе или был отозван. Все четыре причины намеренно возвращают один и тот же ответ — так API не даёт возможности перебором проверить, существует ли вообще конкретный ключ.

Как починить: проверьте, что заголовок передаётся как Authorization: Bearer smg_live_..., и что ключ актуален. Если ключ точно верный — обратитесь к владельцу организации: возможно, ключ отозвали.

missing_scope

HTTP-статус: 403.

Ключ валиден, но у него нет скоупа, необходимого этому эндпоинту. Какой скоуп нужен — смотрите в hint ответа и в Скоупах и правах.

Как починить: попросите владельца организации выпустить новый ключ с нужным скоупом или перевыпустить текущий с расширенным набором.

subscription_inactive

HTTP-статус: 403.

У организации, которой принадлежит ключ, неактивная подписка (закончился триал, а активной подписки нет). API отключается вместе с остальным платным функционалом — это тот же гейт, что и в интерфейсе Smengo.

Как починить: продлите подписку в приложении Smengo (Настройки → Биллинг). Как только подписка снова активна, ключ начинает работать без переиздания.

module_required

HTTP-статус: 403.

Эндпоинт относится к платному модулю, который организация не подключила (какому именно — в hint ответа). Например, /timesheets требует модуль «Табель», а /demand-signals — «Ядро». Права ключа и его скоупы тут ни при чём: не хватает не доступа, а подключённого модуля.

Как починить: подключите нужный модуль в приложении Smengo (Настройки → Биллинг). Ключ начинает работать сразу, переиздавать его не нужно.

not_found

HTTP-статус: 404.

Главный источник этой ошибки — неизвестный путь под /api/v1: любой запрос любым методом к пути, не покрытому ни одним эндпоинтом (например, /api/v1/timesheet вместо /api/v1/timesheets или голый /api/v1), возвращает 404 not_found с message вида No such endpoint: METHOD /path. Редкий второй случай — GET /org, когда для ключа не находится строка организации.

Как починить: проверьте путь запроса по списку эндпоинтов в Обзоре API. Обратите внимание: для фильтров списков (department_id, employee_id) незнакомый id не даёт 404 — там просто возвращается пустой список, см. Конвенции → Фильтры.

method_not_allowed

HTTP-статус: 405.

Эндпоинт существует, но запрошен методом, которого у него нет. Все ресурсы v1 строго read-only, поэтому любой POST, PUT, PATCH или DELETE на существующем эндпоинте возвращает именно этот код. Ответ содержит заголовок Allow со списком поддерживаемых методов; аутентификация при этом не выполняется — ответ одинаков с ключом и без него.

Как починить: используйте метод из заголовка Allow — для v1 это GET (плюс HEAD и OPTIONS). Эндпоинтов для записи в v1 нет.

validation_error

HTTP-статус: 400.

Параметры запроса не прошли валидацию: неизвестный или лишний параметр, from позже to, диапазон дат больше 366 дней, from/to на ресурсе без временно́го измерения и так далее. Причина — в hint.

Как починить: прочитайте hint и поправьте параметры запроса согласно Конвенциям.

invalid_cursor

HTTP-статус: 400.

Значение cursor битое или принадлежит другому набору данных — например, курсор, полученный с одними фильтрами, передан в запрос с другими.

Как починить: не собирайте курсор вручную — используйте только meta.next_cursor из предыдущего ответа того же запроса. Если ошибка повторяется на «свежем» курсоре — начните пагинацию заново без cursor.

rate_limited

HTTP-статус: 429.

Превышен лимит запросов ключа в минуту — rate_limit_per_min (по умолчанию 60, настраивается индивидуально для ключа). Окно скользящее (sliding window, Cloudflare-стиль), а не фиксированное: резкий всплеск ровно на границе минуты не даёт обойти лимит удвоенным числом запросов. Ответ содержит заголовок Retry-After — сколько секунд подождать до следующей попытки, — и, как любой ответ после успешной аутентификации, заголовки X-RateLimit-Limit/X-RateLimit-Remaining/X-RateLimit-Reset (на 401, ранних 403, 404 неизвестного пути, 405 и OPTIONS этих заголовков нет); подробнее — в Конвенциях → Ограничение частоты.

Как починить: снизьте частоту запросов или подождите окно, указанное в Retry-After. Если лимита стабильно не хватает под ваш сценарий — обратитесь в поддержку Smengo для повышения лимита ключа (лимит настраивается на уровне ключа, не организации).

internal_error

HTTP-статус: 500.

Непредвиденная ошибка на стороне Smengo. Такие ошибки логируются и разбираются командой — прикладывать усилия, чтобы «обойти» их на своей стороне, не нужно.

Как починить: повторите запрос позже. Если ошибка повторяется — напишите в поддержку Smengo и укажите request_id из ответа.

Таблица статусов

Код HTTP-статус
unauthorized 401
missing_scope 403
subscription_inactive 403
module_required 403
not_found 404
method_not_allowed 405
validation_error 400
invalid_cursor 400
rate_limited 429
internal_error 500

Каталог исчерпывающий для v1 — других кодов ошибок, кроме этих десяти, не бывает. Он описывает ответы самого приложения: инфраструктура перед ним (CDN, прокси) при сбоях может отдать 502/503 — и не обязательно с JSON-телом. Обрабатывайте такие ответы как временные и повторяйте запрос с экспоненциальной паузой.

Что дальше

Была ли статья полезна?