Документація API/Початок роботи/Помилки

Помилки

Будь-яка відповідь з кодом 400 і вище має однакову форму. Орієнтуйтесь на HTTP-код і error.code; текст error.message призначений для людей і може змінюватись.

Формат

{
  "error": {
    "code": "validation_failed",
    "message": "Продукт вже є у списку",
    "details": [ ... ]            // не завжди: перелік помилок полів
  },
  "message": "Продукт вже є у списку"   // дубль для сумісності
}

У відповідях 4xx можуть бути й інші поля верхнього рівня (наприклад, errors). Ігноруйте їх, усе потрібне є в error. Відповіді 5xx не містять внутрішніх деталей.

Коди

HTTP	error.code	Що сталось	Що робити
400	`bad_request`	Некоректний запит: пошкоджений JSON; невідоме поле в filter / order / fields; невідомий оператор фільтра; некоректний expand.	Виправити запит, не повторювати.
401	`unauthorized`	Немає токена, токен невідомий, вимкнений чи прострочений.	Перевірити токен
403	`forbidden`	Ролі користувача токена бракує права, запис не ваш у режимі «лише свої» або IP поза білим списком.	Додати право ролі / IP.
404	`not_found`	Запису немає або маршрут не існує в API.	Перевірити id і шлях.
409	`conflict`	Конфлікт: `external_id` уже належить іншому запису (у відповіді буде його id).	Оновити знайдений запис через PUT.
409	`idempotency_in_progress`	Запит із цим Idempotency-Key ще виконується.	Повторити через секунду.
422	`validation_failed`	Дані не пройшли перевірку: обов’язкове поле, задовге значення, некоректний варіант доп. поля, чужий field_id, закритий період, бракує залишку, немає платника.	Виправити дані.
422	`idempotency_key_reused`	Idempotency-Key уже використано для іншого запиту.	Новий ключ для нової операції.
429	`rate_limited`	Вичерпано квоту.	Чекати Retry-After
500	`internal_error`	Помилка на нашому боці.	Повторити з `Idempotency-Key`; якщо не минає, пишіть у підтримку.

Приклади

Помилки полів (422)

{
  "error": {
    "code": "validation_failed",
    "message": "Поле обов'язкове для заповнення",
    "details": [ { "field": "first_name", "message": "Поле обов'язкове для заповнення" } ]
  }
}

Доп. поле: варіант списку назвою замість id (422)

{
  "error": {
    "code": "validation_failed",
    "message": "Поле «Регіон»: некоректний формат значення",
    "details": [ { "field": "f_1102", "message": "Поле «Регіон»: некоректний формат значення" } ]
  }
}

Одруківка в операторі фільтра (400)

GET /api/v1/contact?filter[first_name;eqq]=Олена

{
  "error": {
    "code": "bad_request",
    "message": "Некоректний фільтр \"filter[first_name;eqq]\": невідомий оператор \"eqq\" (eq, neq, like, nlike, gt, gte, lt, lte)"
  }
}

details[].field містить ім’я поля в тілі запиту: first_name, channels[0].label; для доп. полів f_<field_id>.

Зайнятий external_id (409)

{
  "error": {
    "code": "conflict",
    "message": "external_id уже використано іншим записом",
    "existing_id": 189,
    "deleted": false
  }
}

Повторювати має сенс лише 409 idempotency_in_progress, 429 і 5xx. Решту треба виправити й надіслати новий запит.