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 — кодів помилок, крім перелічених, не буває.

Що далі

Чи була стаття корисною?