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 — прямая ссылка на описание этого кода на этой странице.
  • 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 (Настройки → Биллинг). Как только подписка снова активна, ключ начинает работать без переиздания.

not_found

HTTP-статус: 404.

Запрошенный конкретный ресурс не существует — или существует, но принадлежит другой организации (тенант-изоляция намеренно не различает эти два случая, чтобы не раскрывать чужие идентификаторы).

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

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 — сколько секунд подождать до следующей попытки, — и, как любой ответ API, заголовки X-RateLimit-Limit/X-RateLimit-Remaining/X-RateLimit-Reset; подробнее — в Конвенциях → Ограничение частоты.

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

internal_error

HTTP-статус: 500.

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

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

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

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

Каталог исчерпывающий для v1 — кодов ошибок, кроме перечисленных, не бывает.

Что дальше

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