Ошибки

Каждый отказ API выглядит одинаково и несёт стабильный код. Ветвитесь по коду, показывайте текст людям и повторяйте только то, что повтор может исправить.

Загружаем поисковый индекс…

Ошибки

Как выглядит отказ

Отказ — application/problem+json, RFC 9457:

ПолеЧто это
typeСтабильный код для ветвления, например insufficient_scope.
titleКороткое описание для людей.
statusСтатус HTTP.
detailЧто случилось в этот раз и что делать.

title и detail — на языке Accept-Language: испанском, английском или русском, по умолчанию английском, — и их формулировки могут меняться: ветвитесь только по type. Некоторые типы добавляют поля, например errors у ошибки проверки или current — нынешнее состояние записи — у конфликта.

Каждый ответ несёт заголовок X-Request-Id. Пишите его в свой журнал: по нему запрос находится в журнале запросов приложения.

Ошибки проверки

Вход строгий: неверное значение, пропущенное поле и неизвестное поле или параметр получают 422 validation_error. errors перечисляет сообщения по полям; вложенные поля пишутся через точку, например variants.0.price.

Запрос
curl -X POST "https://api.saleya.app/v1/inventory-levels/set" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'Idempotency-Key: 0b4a9a3c-6c4e-4f0e-9a43-2f8f6d1b7e21' \
  -H "Content-Type: application/json" \
  -d '{
  "variant_id": 1042,
  "location_id": 3,
  "on_hand": "24"
}'
Ответ
HTTP/1.1 422 Unprocessable Content

{
  "type": "validation_error",
  "title": "Validation failed",
  "status": 422,
  "errors": {
    "expected_on_hand": [
      "The expected on hand field is required."
    ]
  }
}

Статусы

СтатусЧто значитЧто делать
401Токена нет, он неверен, истёк или отозван.Исправьте токен: повтор не поможет.
403У приложения нет scope, адрес не разрешён или в тарифе нет API.Измените доступ приложения в магазине.
404Такой записи нет — или она другого магазина.Проверьте ID.
409Запрос противоречит состоянию магазина: исчерпан потолок, ID занят, магазин отказал в изменении.Прочитайте type и current и решите.
410Курсор синхронизации устарел.Синхронизируйте заново без курсора — страницы и синхронизация.
412, 428Версия в If-Match устарела или её нет.Прочитайте запись и повторите — версии и If-Match.
422Запрос неверен.Исправьте поля из errors.
429Лимит запросов исчерпан.Подождите Retry-After секунд — лимиты запросов.
500, 503Сбой на нашей стороне или обслуживание.Повторите после Retry-After с тем же Idempotency-Key.
503 store_frozenМагазин заморожен за неоплату подписки.Повтор не поможет: магазину нужно оплатить подписку, после этого запросы заработают сразу.

Что повторять

  • Сетевая ошибка или таймаут: повторите тот же запрос с тем же Idempotency-Key. Если он прошёл, вы получите сохранённый ответ, — идемпотентность.
  • 429 и 503: через Retry-After секунд.
  • 409 idempotency_key_in_use: первый запрос с этим ключом ещё идёт; повторите через Retry-After.
  • 503 transient_conflict: параллельное изменение откатило запрос, ничего не записано; повторите его.
  • Любой другой 4xx: не как есть — сначала измените запрос.

Все типы ошибок

Каждый type со статусом, смыслом и тем, что делать, — в каталоге ошибок.

Следующий гайдИдемпотентность