Помилки API

API повідомляє про помилки стандартними кодами стану HTTP та єдиним тілом відповіді. Успішні відповіді повертають дані безпосередньо, без обгортки-конверта.

Формат помилки

При помилці тіло відповіді — це JSON-об'єкт з одним полем error, що містить людиночитане повідомлення:

{"error":"reaction not found"}

Орієнтуйтесь насамперед на код стану HTTP, а текст error використовуйте для логів і підказок користувачу.

Коди стану

  • 200 OK — запит успішний, у тілі дані.
  • 201 Created — створено новий ресурс (частина POST-ендпоінтів).
  • 204 No Content — успіх без тіла (частина видалень).
  • 400 Bad Request — некоректне тіло або параметри запиту.
  • 401 Unauthorized — токен відсутній, невірний або прострочений; або маршрут недоступний за персональним токеном.
  • 402 Payment Required — дія упирається в тариф або квоту (наприклад, власне медіасховище потребує premium).
  • 403 Forbidden — токену не вистачає потрібної області доступу для цього маршруту.
  • 404 Not Found — ресурс не знайдено або він вам не належить.
  • 409 Conflict — конфлікт стану (наприклад, дубль унікального значення).
  • 422 Unprocessable Entity — тіло синтаксично валідне, але не проходить перевірок предметної області.
  • 429 Too Many Requests — перевищено ліміт запитів (див. ліміти).
  • 500 Internal Server Error — внутрішня помилка сервера; спробуйте пізніше.

Як обробляти

Вважайте успіхом коди 2xx. На 401/403 перевірте токен і його області доступу. На 4xx (крім 429) не повторюйте запит без змін — виправте запит. На 429 і 5xx доречний повтор з експоненційною затримкою.

Що далі