Коды ошибок

Формат ошибки один на все методы. Разбирать текст сообщения не нужно и вредно: он меняется, а code - нет.

Формат

json

{
  "error": {
    "code": "validation_failed",
    "message": "stock должен быть целым неотрицательным числом",
    "field": "items[2].stock",
    "request_id": "req_7f31c0a8"
  }
}

HTTP-коды

Код	Значит	Что делать
`400`	Запрос не разобрался	Смотреть тело: скорее всего, битый JSON
`401`	Ключ не передан или отозван	Проверить заголовок и контур ключа
`403`	Ключу не хватает права	Права выдаются в кабинете на конкретные методы
`404`	Нет такого `sku` или заказа	Проверить код позиции, он чувствителен к регистру
`409`	Конфликт состояния	Перечитать объект и повторить с новой версией
`422`	Значение не прошло проверку	Поле указано в `field`
`429`	Превышен лимит	Ждать `Retry-After` секунд
`503`	Идут работы или перегрузка	Повторять с растущей задержкой

Коды сервиса

code	Когда приходит
`sku_not_found`	Позиции с таким кодом нет в каталоге контура
`stock_negative`	Прислан отрицательный остаток
`price_below_min`	Цена ниже минимальной для категории
`state_transition`	Переход статуса не разрешён, текущий статус в теле
`order_locked`	Заказ на сборке, состав менять нельзя
`batch_too_large`	В пакете больше позиций, чем разрешено контуру
`idempotency_conflict`	Тот же ключ с другим телом запроса
`signature_mismatch`	Подпись вебхука не сошлась (см. проверку подписи)

Повторы

Повторять стоит только 429, 500, 502, 503 и 504. Все остальные ответы повтор не чинит: он лишь съедает лимит. Задержку берите растущей - 1, 2, 4, 8 секунд со случайной добавкой, - иначе после сбоя все клиенты приходят одной волной в одну и ту же секунду.

409 - это не сбойКонфликт означает, что объект успели изменить. Правильная реакция - перечитать его и решить, нужна ли правка, а не слать тот же запрос в цикле.

Если не сходится

В каждом ответе есть request_id, он же в заголовке X-Request-Id. Мы храним запросы 30 дней и по этому идентификатору видим тело, заголовки и время. Приложите его к обращению из кабинета: без него разбор начинается с поиска запроса, а с ним - сразу с причины.