Ошибки

Любая ошибка приходит одним и тем же телом, с любым статусом 4xx или 5xx:

{
  "detail": "Понятное человеку описание, что пошло не так",
  "code": "machine_readable_code"
}

detail – текст для логов, его формулировка может меняться.

code – стабильный код. Реализуйте логику по нему.

Коды состояния

Статус	`code`	Когда
`400`	`bad_request`	Битые параметры или невалидное тело.
`401`	`unauthorized`	Нет заголовка `X-API-Key` или ключ неверный.
`402`	`payment_required`	Доступ к API приостановлен. Что именно произошло, написано в `detail`.
`403`	`forbidden`	Не хватает прав: запись ключом на чтение или чужой ресурс.
`403`	`session_required`	Операция выполняется только из личного кабинета. Никакой ключ на неё не действует.
`404`	`not_found`	Ресурс не найден или принадлежит другому аккаунту.
`405`	`method_not_allowed`	Метод не поддерживается этим адресом.
`409`	`conflict`	Конфликт состояния, например дубликат.
`422`	`validation_error`	Тело или параметры не прошли проверку схемы.
`429`	`rate_limited`	Слишком много запросов подряд. Повторите с задержкой.
`500`	`internal_error`	Наша ошибка. Стоит повторить с нарастающей задержкой.
`503`	`service_unavailable`	Сервис временно недоступен. Повторите с задержкой.

Адресация и папки

Статус	`code`	Когда
`400`	`object_or_folder_required`	В запросе отзывов или аналитики нет ни `object_id`, ни `folder_id`.
`400`	`object_and_folder_conflict`	Переданы оба сразу. Адресовать нужно ровно один.
`400`	`folder_depth_exceeded`	Нарушена глубина: родитель сам вложен, у папки есть подпапки, или её делают родителем самой себе.
`403`	`folder_limit_reached`	Достигнут потолок в 1000 живых папок на аккаунт.
`404`	`folder_not_found`	Папка не найдена или чужая.
`409`	`folder_not_empty`	У папки есть живые подпапки. Сначала перенесите или удалите их.

Статус	`code`	Когда
`403`	`object_limit_reached`	Достигнут потолок активных объектов на вашем тарифе.
`403`	`object_creation_budget_exhausted`	Исчерпан бюджет пересозданий объектов. Это защита от абьюза, а не тарифный лимит: как поднять – написано в `detail`.
`402`	`source_requires_upgrade`	Площадка не входит в ваш тариф.
`400`	`pinned_limit_exceeded`	Закреплённых отзывов на объект не больше 30.
`400`	`duplicate_review_ids`	В `ordered_review_ids` есть повторы.
`409`	`idempotency_conflict`	Тот же `Idempotency-Key` пришёл с другим телом запроса.
`409`	`idempotency_in_progress`	Запрос с этим `Idempotency-Key` ещё выполняется. Повторите позже.

Отказы по отдельным ссылкам при создании объекта и добавлении площадок ошибкой не считаются: они приходят внутри 201, в поле error_code каждой ссылки – source_not_detected, source_url_invalid, source_requires_upgrade, source_already_linked, link_already_added.

Синхронизация отзывов

Статус	`code`	Когда
`400`	`invalid_cursor`	Курсор не читается: испорчен, изменён или выдан другому аккаунту. Начните обход заново, без `cursor` – как это работает.
`400`	`cursor_mismatch`	Вместе с курсором передан `object_id`, `folder_id` или `mode`, не совпадающий с тем, для которого курсор выдан.

Ответы на отзывы

Статус	`code`	Когда
`402`	`reply_requires_upgrade`	Публикация ответов входит в тариф «Полный». Удалить уже опубликованный ответ можно на любом тарифе.
`403`	`reply_access_revoked`	Площадка не даёт нам отвечать по этой ссылке: доступ был и отозван. Что сделать, написано в `detail`.
`404`	`reply_not_found`	У этого отзыва нет вашего ответа. Ответ, написанный не через нас, виден как `reply_text` самого отзыва.
`409`	`reply_not_supported`	На этой площадке мы пока не публикуем ответы. Смотрите `can_publish_reply` в `GET /v3/sources`.
`409`	`reply_owned_by_other_account`	На отзыв уже отвечает другой аккаунт: на площадке место под ответ одно.
`409`	`reply_in_progress`	Предыдущий ответ сейчас публикуется, отменить его нечем. Повторите через несколько секунд.
`409`	`reply_edit_not_supported`	На этой площадке опубликованный ответ нельзя переписать.
`409`	`reply_delete_not_supported`	На этой площадке ответ нельзя удалить.
`422`	`validation_error`	Текст пуст, содержит управляющие символы или длиннее допустимого на площадке.

202 означает, что задачу мы приняли; опубликованный ответ виден в самом отзыве (reply_text) и приходит событием replies.new. Если ответ не появился, причина обычно одна из этих – и почти все мы отрабатываем сами:

Причина	Что происходит
Наш доступ к площадке обновляется	Ничего делать не нужно, ответ уйдёт сам.
Площадка просит подождать	Повтор произойдёт автоматически.
Сеть или сбой на стороне площадки	Повторим сами, до трёх раз.
Из ссылки не выводится объект площадки	Проверьте адрес ссылки в объекте.
Площадка отклонила текст	Единственный случай, где нужны вы: измените текст и отправьте снова.

Ответ не появился – напишите на info@rewio.ru.

Как обрабатывать

Повторяйте 429 и 5xx с нарастающей задержкой. Остальные 4xx повторять бессмысленно – запрос надо чинить.
Логируйте code вместе с detail: по коду мы быстрее поймём, что случилось.
При добавлении ссылок отказ приходит по каждой ссылке отдельно: текст в error, машинная причина в error_code. Негодная ссылка не отменяет остальные – они добавятся. Форматы адресов смотрите в Форматах ссылок.

Примеры:

// 401 – ключ не передан
{ "detail": "Missing API key", "code": "unauthorized" }

// 403 – запись ключом на чтение
{ "detail": "This key is read-only", "code": "forbidden" }

// 422 – невалидное тело
{ "detail": "url: field required", "code": "validation_error" }