Ошибки

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

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

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

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

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

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

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

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

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

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

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

Статус	`code`	Когда
`402`	`reply_requires_upgrade`	Публикация ответов входит в тариф «Полный». Снять уже опубликованный ответ можно на любом тарифе.
`402`	`reply_requires_upgrade`	Ответы входят в тариф «Полный». На вашем тарифе публикация недоступна.
`403`	`reply_access_revoked`	Площадка не даёт нам отвечать по этой ссылке: доступ был и отозван. Что сделать, написано в `detail`.
`404`	`reply_not_found`	У этого отзыва нет вашего ответа. Ответ, написанный не через нас, виден как `reply_text` самого отзыва.
`409`	`reply_not_supported`	На этой площадке мы пока не публикуем ответы. Смотрите `can_publish_reply` в `GET /v2/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. Негодная ссылка не отменяет остальные: они добавятся. Форматы адресов смотрите в Форматах ссылок.

Примеры:

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

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

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