Ошибки

Ошибка с любым статусом 4xx или 5xx приходит в одном формате:

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

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

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

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

Статус	`code`	Когда
`400`	`bad_request`	Запрос корректен по схеме, но не прошёл проверку на сервере.
`401`	`unauthorized`	Нет заголовка `X-API-Key` или ключ неверный.
`402`	`access_suspended`	Доступ к API приостановлен: отклоняются все запросы, кроме `DELETE`.
`402`	`access_expired`	Оплаченный период закончился: работают чтение и `DELETE`, остальная запись отклоняется.
`403`	`forbidden`	Не хватает прав: запись ключом `read_only`.
`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`	Когда
`402`	`refresh_requires_upgrade`	Дополнительный сбор отзывов входит в тариф «Полный».
`402`	`refresh_trial_exhausted`	Все 5 дополнительных сборов пробного периода использованы. На тарифе «Полный» дополнительный сбор доступен раз в сутки для каждого объекта.
`409`	`refresh_in_progress`	Сбор по объекту уже идёт. Итог – в `GET /v3/objects/{object_id}/refresh`.
`409`	`refresh_nothing_to_scrape`	У объекта нет ссылок, которые можно собрать.
`429`	`refresh_limited`	Дополнительный сбор по объекту был меньше суток назад, собирать ещё раз нечего. `Retry-After` – секунд до следующего сбора.

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

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

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

Статус	`code`	Когда
`402`	`reply_requires_upgrade`	Публикация ответов и «Пропустить» входят в тариф «Полный». Удалить уже опубликованный ответ можно на любом тарифе.
`402`	`reply_trial_quota_exhausted`	Пробный доступ включает три ответа на каждую площадку, и они израсходованы. Лимит снимает переход на «Полный».
`403`	`reply_card_not_yours`	Объект не закреплён за вашим аккаунтом. Мы отвечаем от имени организации, поэтому публикуем только там, где подтверждено, что объект ваш. Чтобы подтвердить, напишите в поддержку.
`403`	`reply_access_revoked`	Площадка не даёт нам отвечать по этой ссылке: доступ был, но его отозвали. Что сделать, написано в `detail`.
`404`	`reply_not_found`	Ответа нет. Для `GET /reply` – нет ответа через нас (написанный не через нас виден как `reply_text` отзыва); для `DELETE` – на отзыве нет никакого ответа.
`409`	`reply_not_supported`	На этой площадке мы пока не публикуем ответы. Смотрите `can_publish_reply` в `GET /v3/sources`.
`409`	`reply_not_replyable`	Отзыв не нативен для площадки: она показывает его в своей ленте, но собран он с другой (`provider` ≠ `source_slug`: `tbank`, `booking`, `tripadvisor`, …). Ответить на него через эту площадку нельзя.
`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.

Жалобы на отзывы

Статус	`code`	Когда
`402`	`complaint_requires_upgrade`	Жалобы входят в тариф «Полный».
`402`	`complaint_trial_quota_exhausted`	Пробный доступ включает три жалобы на каждую площадку, и они израсходованы.
`403`	`complaint_access_missing`	На этой карточке у вас не подключены ответы – а жалобы живут там же.
`403`	`complaint_card_not_yours`	Объект не закреплён за вашим аккаунтом. Чтобы подтвердить, напишите в поддержку.
`409`	`complaint_not_supported`	На этой площадке мы не подаём жалобы. Смотрите `can_file_complaint` в `GET /v3/sources`.
`409`	`complaint_not_replyable`	Отзыв собран с другой площадки (`provider` ≠ `source_slug`): жаловаться на него нужно там.
`409`	`complaint_already_filed`	На отзыв уже подана жалоба, а площадка принимает одну (Яндекс).
`409`	`complaint_pending_review`	Прежняя жалоба ещё на рассмотрении (2ГИС).
`409`	`complaint_cooldown`	Повторно – не чаще раза в трое суток (Google). Когда можно, говорит заголовок `Retry-After` и `retry_at` в форме.
`409`	`complaint_in_progress`	Жалоба на этот отзыв сейчас отправляется.
`422`	`complaint_category_invalid`	Нет `category` или код не из `form.categories`.
`422`	`complaint_text_required`	Площадка принимает жалобу текстом, а `text` пуст.
`422`	`complaint_text_too_long`	`text` длиннее `form.max_length`.
`422`	`complaint_text_invalid`	В `text` управляющие символы.
`503`	`complaint_source_paused`	Подача жалоб на площадке временно приостановлена: у площадки сбой.

Если жалоба не подана уже после 202, у неё status: failed и error.code из того же словаря:

за время отправки что-то изменилось – complaint_requires_upgrade, complaint_trial_quota_exhausted, complaint_access_missing, complaint_access_revoked (доступ к площадке отозван), complaint_card_not_yours, complaint_source_paused, complaint_already_filed;
отзыв или площадка – complaint_not_replyable (отзыва больше нет на площадке), complaint_target_unresolved (не нашли отзыв на площадке), complaint_not_supported;
площадка не приняла – complaint_rejected_by_platform;
не удалось за сутки – complaint_session_expired, complaint_rate_limited или complaint_transport_failed.

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

Повторяйте 429 и 5xx с нарастающей задержкой. Исключение – 429 refresh_limited: раньше Retry-After дополнительный сбор по объекту не запустится. Остальные 4xx не повторяйте без исправления запроса; исключения – 409 idempotency_in_progress и 409 reply_in_progress, их повторяют с задержкой.
Логируйте code вместе с detail: по коду мы быстрее поймём, что случилось.
При добавлении ссылок отказ приходит по каждой ссылке отдельно: текст в error, машинная причина в error_code. Негодная ссылка не отменяет остальные – они добавятся. Форматы адресов смотрите в разделе «Форматы ссылок».

Примеры:

// 401 – ключ не передан
{ "detail": "API key required. Provide X-API-Key header.", "code": "unauthorized" }

// 403 – запись ключом на чтение
{ "detail": "This operation requires full access. Your API key has read-only access.", "code": "forbidden" }

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