Ошибки · Rentu API

Структура#

json

{
  "success": false,
  "error": {
    "code": "plan_required",
    "message": "Endpoint requires PRO plan",
    "details": { "required_plan": "pro", "current_plan": "basic" }
  }
}

Все коды#

Учётные данные#

Код	HTTP	Когда	Что делать
`unauthorized`	401	Нет токена, токен испорчен или подписан не тем секретом; ключ неизвестен, отключён или секрет неверен	Проверить учётные данные. Повтор без изменений не поможет
`token_expired`	401	Истёк час жизни токена	Получить новый токен и повторить запрос

Права и тариф#

Код	HTTP	Когда	Что делать
`forbidden_sc`	403	У сотрудника, которому принадлежит ключ, нет прав на этот метод или этот торговый центр	Проверить его роли в ТЦ. Повтор не поможет
`plan_required`	403	Метод или значение параметра доступны только на PRO. В `details` придут `required_plan` и `current_plan`	Перейти на PRO либо использовать доступное значение
`payment_required`	402	У торгового центра ограничение из-за оплаты	Вопрос к торговому центру, не технический
`subscription_suspended`	402	Доступ торгового центра приостановлен	То же

Данные#

Код	HTTP	Когда	Что делать
`not_found`	404	Не найден торговый центр, точка или зона; либо запрошенный идентификатор принадлежит другому ТЦ	Проверить идентификаторы
`traffic_not_configured`	404	В торговом центре не настроена система подсчёта посещаемости	Повторять бесполезно: `attendance` и `traffic_areas` не заработают, пока ТЦ не подключит подсчёт
`already_exists_in_sc`	409	`POST /events`: событие с такими же названием, типом и датами уже есть	Считать событие созданным. Молча подменять существующее API не будет

Параметры#

Код	HTTP	Когда	Что делать
`period_too_long`	422	Запрошенный период больше, чем разрешает тариф ТЦ	Разбить период или перейти на PRO
`fresh_data_requires_pro`	422	На Basic запрошен сегодняшний день	Ставить `end_date` не позже вчера либо перейти на PRO
`too_long_date`	422	Превышено фиксированное окно метода: 31 день для почасовой посещаемости, 31 день для чеков	Сузить период. Это не тарифное ограничение, PRO не поможет
`validation_error`	422	Любая другая ошибка входа: неизвестное значение перечисления, `end_date` раньше `start_date`, `per_page` вне диапазона, неразобранная дата	Исправить по `details`

Временные сбои#

Код	HTTP	Когда	Что делать
`rate_limited`	429	Превышен лимит частоты	Подождать `Retry-After` секунд
`rights_unavailable`	503	Сервис прав не ответил	Повторить с задержкой
`traffic_unavailable`	503	Не ответила подсистема подсчёта посещаемости	Повторить с задержкой
`query_timeout`	504	Выборка не уложилась в отведённое время. Обычно причина в слишком широком периоде на точке с большим объёмом чеков	Сузить период и повторить
`internal_error`	500	Непредвиденная ошибка на нашей стороне	Повторить с задержкой; если повторяется — написать нам

Что повторять, а что нет#

Повторять имеет смысл ровно шесть кодов:

token_expired        → сначала обновить токен
rate_limited         → выждать Retry-After
rights_unavailable   → экспоненциальная задержка
traffic_unavailable  → экспоненциальная задержка
query_timeout        → сузить период, затем повторить
internal_error       → экспоненциальная задержка

Остальные коды описывают состояние, которое само не изменится: неверные параметры, отсутствие прав, недостаточный тариф, блокировка ТЦ. Повтор только съест лимит.

Отдельно стоит rights_unavailable. Когда сервис прав недоступен, мы не отдаём данные, а возвращаем 503. Открыть доступ «потому что не смогли проверить» нельзя: у сотрудника права могли уже отобрать. Интеграцию стоит строить так, чтобы 503 означал «попробуем позже», а не «данных нет».

Пример разбора#

python

resp = session.get(url, headers=headers)
body = resp.json()

if body.get("success"):
    handle(body["data"])
else:
    code = body["error"]["code"]
    if code == "token_expired":
        refresh_token(); retry()
    elif code == "rate_limited":
        sleep(int(resp.headers.get("Retry-After", 60))); retry()
    elif code in ("rights_unavailable", "traffic_unavailable", "internal_error"):
        backoff_retry()
    else:
        log_and_stop(code, body["error"]["message"])

Тексты в message написаны по-русски и предназначены человеку. Привязываться к ним в коде не стоит: они могут меняться, а code не меняется.