Как выглядит отказ
Отказ — 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 со статусом, смыслом и тем, что делать, — в каталоге ошибок.