Коды ошибок

API никогда не возвращает локализованный текст. Любая ошибка — JSON-конверт со стабильным машиночитаемым кодом; код вы сопоставляете со своими строками.

Конверт

statusCode повторяет HTTP-статус, code — стабильный идентификатор, message — англоязычная подсказка разработчику, которая может измениться в любой момент, а details несёт структурированный контекст для части кодов (например, каких товаров не хватило).

application/json

{
  "statusCode": 409,
  "code": "ERR_OUT_OF_STOCK",
  "message": "insufficient stock for 2 items",
  "details": { "items": [{ "productId": "…", "requested": 5, "available": 2 }] }
}

Сопоставляйте по code, никогда по message

message написан для человека, читающего лог. Он не входит в контракт и не переводится; code — входит.

Каталог

Кодов: 98

Общие

Общие
Код	Значение
`ERR_VALIDATION`	Тело запроса или параметры не прошли валидацию; details перечисляет проблемные поля.
`ERR_BAD_REQUEST`	Запрос сформирован неверно так, что валидация не может это описать.
`ERR_UNAUTHORIZED`	Учётные данные не переданы или access-токен истёк.
`ERR_FORBIDDEN`	Аутентификация прошла, но действие не разрешено.
`ERR_NOT_FOUND`	Ресурс не существует или вам не виден.
`ERR_CONFLICT`	Запись конфликтует с параллельной операцией; повторите запрос.
`ERR_RATE_LIMITED`	Слишком много запросов по этому ключу. Подождите столько секунд, сколько в Retry-After.
`ERR_INTERNAL`	Неожиданная ошибка сервера. Можно безопасно повторить с задержкой.
`ERR_NETWORK`	Запрос не дошёл до API (сеть, DNS или CORS).
`ERR_UNKNOWN`	Нераспознанная ошибка; посмотрите сырой ответ.

Аутентификация и учётные записи

Аутентификация и учётные записи
Код	Значение
`ERR_OTP_INVALID`	Одноразовый код не совпадает.
`ERR_OTP_EXPIRED`	Одноразовый код истёк; запросите новый.
`ERR_OTP_RATE_LIMITED`	Слишком много запросов кода для этого номера или адреса эл. почты.
`ERR_OTP_TOO_MANY_ATTEMPTS`	Слишком много неверных кодов; запросите новый.
`ERR_USER_BLOCKED`	Учётная запись заблокирована; все её токены отклоняются.
`ERR_STAFF_PHONE_EXISTS`	Пользователь с таким номером телефона уже существует.
`ERR_PHONE_REQUIRED`	У этой учётной записи нет контактного номера телефона — добавьте его перед оформлением заказа.
`ERR_CONTACT_TAKEN`	Этот номер телефона или адрес эл. почты уже принадлежит другой учётной записи.
`ERR_CHANNEL_DISABLED`	Этот способ входа здесь отключён — используйте другой.

Партнёрский API, ключи и вебхуки

Партнёрский API, ключи и вебхуки
Код	Значение
`ERR_API_KEY_INVALID`	Заголовок X-Api-Key отсутствует или не совпадает ни с одним ключом.
`ERR_API_KEY_REVOKED`	Ключ отозван либо его льготный период после ротации истёк.
`ERR_API_KEY_SCOPE`	Ключ валиден, но не содержит скоуп, который нужен этому эндпоинту.
`ERR_API_KEY_ENVIRONMENT`	Sandbox-ключ отправлен в боевой API или наоборот.
`ERR_API_KEY_LIMIT`	У вас уже максимальное количество активных ключей.
`ERR_WEBHOOK_URL_INVALID`	URL эндпоинта должен быть https (http допустим только для localhost вне продакшена).
`ERR_WEBHOOK_LIMIT`	У этого ключа уже максимальное количество вебхуков.
`ERR_WEBHOOK_DISABLED`	Этот вебхук отключён — включите его перед отправкой теста.
`ERR_PARTNER_ORDER_NOT_ASSIGNED`	Заказ не назначен вашему партнёрскому аккаунту.

Платежи

Платежи
Код	Значение
`ERR_PAYMENT_METHOD_UNAVAILABLE`	Этот способ оплаты отключён в данной среде.
`ERR_PAYMENT_PROVIDER_UNAVAILABLE`	Провайдер карт не настроен или не ответил.
`ERR_PAYMENT_INTENT_INVALID_STATE`	Платёжное намерение не в том статусе, чтобы выполнить это действие.
`ERR_PAYMENT_SIGNATURE_INVALID`	Подпись вебхука провайдера не прошла проверку.
`ERR_PAYMENT_ALREADY_PAID`	Заказ уже оплачен.

Заказы

Заказы
Код	Значение
`ERR_NO_DEFAULT_ADDRESS`	У клиента нет адреса доставки по умолчанию.
`ERR_OUT_OF_STOCK`	Одна или несколько позиций превышают остаток; details их перечисляет.
`ERR_PRODUCT_UNAVAILABLE`	Товар в заказе больше нельзя купить.
`ERR_OUT_OF_ZONE`	Адрес доставки вне всех активных зон доставки.
`ERR_ORDER_NOT_CANCELLABLE`	Заказ прошёл стадию, на которой его можно отменить.
`ERR_ORDER_NOT_RATABLE`	Оценить можно только доставленный заказ.
`ERR_ALREADY_RATED`	У этого заказа уже есть оценка.
`ERR_INVALID_TRANSITION`	Машина состояний заказа отклоняет переход из текущего статуса.
`ERR_IDEMPOTENCY_KEY_REQUIRED`	Для этой записи нужен заголовок Idempotency-Key.
`ERR_IDEMPOTENCY_CONFLICT`	Тот же Idempotency-Key использован с другим телом запроса.
`ERR_ORDER_NOT_ACCEPTABLE`	Заказ не в том статусе, когда продавец может его принять или отклонить.
`ERR_ORDER_ALREADY_CLAIMED`	Этот заказ уже взял другой сборщик.
`ERR_ORDER_NOT_CLAIMED`	Заказ не закреплён за вами.
`ERR_ORDER_NOT_PACKABLE`	Заказ не в том состоянии, чтобы его упаковать, переупаковать или напечатать документы.

Каталог и продавцы

Каталог и продавцы
Код	Значение
`ERR_VENDOR_NOT_FOUND`	Профиль продавца для этого пользователя или id не найден.
`ERR_ITEMS_ALREADY_DECIDED`	Эти позиции заказа уже приняты или отклонены.
`ERR_PRODUCT_NOT_OWNED`	Товар принадлежит другому продавцу.
`ERR_CATEGORY_INVALID`	Идентификатор категории неизвестен или это не конечная категория.
`ERR_SKU_CONFLICT`	Сгенерированный SKU совпал с существующим.
`ERR_MEDIA_UNAVAILABLE`	Объектное хранилище не настроено или недоступно.
`ERR_MEDIA_INVALID`	Загрузка отклонена: неверный тип содержимого или слишком большой размер.
`ERR_CATEGORY_NOT_EMPTY`	В категории ещё есть товары или подкатегории.
`ERR_CATEGORY_CYCLE`	Перенос сделал бы категорию собственным предком.

Диспетчеризация и доставка

Диспетчеризация и доставка
Код	Значение
`ERR_PICKUP_INCOMPLETE`	Собраны ещё не все принятые позиции.
`ERR_ITEM_NOT_PICKABLE`	Эта позиция не в том статусе, чтобы её собрать.
`ERR_DRIVER_NOT_FOUND`	Профиль водителя для этого пользователя не найден.
`ERR_DRIVER_OFFLINE`	Водитель не в сети, поэтому партию предложить нельзя.
`ERR_DRIVER_BUSY`	У водителя уже есть активная партия.
`ERR_BATCH_NOT_OFFERED`	Партия сейчас не предложена этому водителю.
`ERR_OFFER_EXPIRED`	90-секундное окно принятия истекло.
`ERR_BATCH_NOT_ASSIGNED`	Партия не назначена этому водителю.
`ERR_SCAN_INCOMPLETE`	Сканирующий шлюз не выпустил в рейс: отсканированы не все позиции.
`ERR_SCAN_WRONG_BATCH`	Этот штрихкод принадлежит позиции из другой партии.
`ERR_STOP_ALREADY_RESOLVED`	Точка уже доставлена или отмечена как неудачная.
`ERR_BATCH_INCOMPLETE`	В партии остались нерешённые точки.
`ERR_COD_VARIANCE_NOTE_REQUIRED`	Собранная наличность отличается от ожидаемой; нужен комментарий.
`ERR_BATCH_INVALID_TRANSITION`	Машина состояний партии отклоняет этот переход.
`ERR_ROUTE_UNAVAILABLE`	Провайдер маршрутов недоступен, и запасной способ не смог построить маршрут.
`ERR_DELIVERY_RETRY_LIMIT`	По этому заказу уже исчерпаны повторные попытки.
`ERR_ITEM_NOT_EXPECTED`	Отсканированная позиция здесь не ожидается: заказ отменён или продавец её отклонил.
`ERR_INTAKE_INCOMPLETE`	Приёмку нельзя завершить — часть принятых позиций заказа ещё не отсканирована на хабе.
`ERR_PARCEL_NOT_IN_BATCH`	Код посылки не относится ни к одному заказу загружаемого рейса.
`ERR_WRONG_STOP_PARCEL`	Отсканированная у двери посылка относится к другой точке маршрута; как доставка она не записывается.
`ERR_PARCEL_NOT_LOADED`	Эту посылку не загружали в фургон этой партии, поэтому передать её у двери нельзя.
`ERR_OUTSIDE_GEOFENCE`	Позиция дальше от адреса точки, чем допускает геозона доставки, и причина не указана.
`ERR_DELIVERY_SCAN_INCOMPLETE`	Прежде чем отметить доставку, у двери нужно отсканировать каждую посылку точки.
`ERR_LOCATION_REQUIRED`	Маршрут нельзя начать без свежего онлайн-сигнала присутствия водителя.

Поддержка, возвраты и возвраты товара

Поддержка, возвраты и возвраты товара
Код	Значение
`ERR_TICKET_CLOSED`	Тикет поддержки закрыт и не принимает новых сообщений.
`ERR_TICKET_NOT_ASSIGNABLE`	Тикет нельзя назначить этому агенту.
`ERR_CSAT_NOT_ALLOWED`	Оценку удовлетворённости можно оставить только по решённому или закрытому тикету.
`ERR_CSAT_ALREADY_GIVEN`	По этому тикету уже есть оценка удовлетворённости.
`ERR_REFUND_AMOUNT_EXCEEDS`	Возврат превысил бы оплаченную или уже возвращённую по заказу сумму.
`ERR_REFUND_INVALID_STATE`	Возврат не в том статусе, чтобы выполнить это действие.
`ERR_REFUND_ORDER_NOT_ELIGIBLE`	Заказ в текущем статусе не подлежит возврату средств.
`ERR_RETURN_NOT_ELIGIBLE`	Заказ в текущем статусе не подлежит возврату товара.

Администрирование платформы

Администрирование платформы
Код	Значение
`ERR_DEPENDENCY_UNAVAILABLE`	Внутренний сервис (Redis) был недоступен — запрос не применён. Можно безопасно повторить с задержкой.
`ERR_ZONE_INVALID_POLYGON`	Полигон зоны доставки не является корректным замкнутым контуром.
`ERR_SETTLEMENT_EXISTS`	Расчёт для этого продавца и периода уже существует.
`ERR_SETTLEMENT_INVALID_STATE`	Расчёт не в том статусе, чтобы выполнить это действие.
`ERR_SETTLEMENT_PERIOD_OPEN`	Расчётный период ещё не закончился.
`ERR_SETTING_UNKNOWN`	Настройки платформы с таким ключом нет.
`ERR_SETTING_INVALID`	Значение настройки вне допустимого диапазона или типа.
`ERR_COUPON_INVALID`	Код купона не применяется — неизвестен, истёк, ещё не начался, исчерпан лимит использований или не достигнута минимальная сумма заказа.
`ERR_COUPON_CODE_TAKEN`	Купон с таким кодом уже существует; коды уникальны.
`ERR_LOYALTY_INSUFFICIENT`	Заказ пытается списать больше баллов Turan, чем есть на счёте.