Ошибки 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 уместен повтор с экспоненциальной задержкой.

Что дальше