Ошибки и лимиты

Сколько запросов можно делать, что значат коды ошибок и когда повторять запрос.

Лимиты

Что	Бесплатный тариф	Платные тарифы и свои сайты
Ключей	1	10
Вебхуков	1	20
Запросов в минуту на ключ	60	600

Сверх лимита — 429 rate_limited и заголовок Retry-After: через сколько секунд повторять. Товаров и разделов — сколько позволяет тариф; больше — 409 products_limit и 409 categories_limit.

Больше 30 неверных ключей в минуту с одного IP-адреса — тоже 429 rate_limited.

Формат ошибки

JSON

{"error": {"code": "not_found", "message": "Не найдено"}}

Коды ошибок

Код	HTTP	Что значит
`missing_key`	401	Нет заголовка `Authorization: Bearer oks_…`
`invalid_key`	401	Ключ не найден или отозван
`insufficient_scope`	403	У ключа нет права на это действие
`rate_limited`	429	Слишком много запросов, повторите через минуту (`Retry-After`)
`not_found`	404	Объекта или пути нет
`method_not_allowed`	405	Метод для этого пути не поддерживается
`bad_json`	400	Тело запроса — не JSON
`bad_cursor`	400	Неверный `cursor`
`bad_date`	400	Неверная дата в `updated_since`, нужен ISO 8601
`products_limit`	409	Достигнут лимит товаров тарифа
`categories_limit`	409	Достигнут лимит разделов тарифа
`name_required`	422	Нужно название
`variants_required`	422	Нужен хотя бы один вариант (пустой список `variants` не принимается)
`bad_variants`	422	Неверный список вариантов или позиций
`variant_not_found`	422	Вариант не найден или принадлежит другому товару
`bad_price`	422	Цена — число от 0 до 1 000 000 000
`bad_stock`	422	Остаток — целое число от 0 до 1 000 000 000 или `null`
`bad_images`	422	Фото — список ссылок `http(s)://…`
`bad_categories`	422	Неверный список разделов, или раздела нет
`bad_brand`	422	Нет такого бренда
`bad_parent`	422	Родительский раздел не найден или создаёт цикл
`items_required`	422	Нужен непустой список `items`
`too_many_items`	422	Слишком много позиций за один запрос (остатки — 500, заказ — 100)
`customer_required`	422	Нужно имя, телефон или почта покупателя
`bad_email`	422	Неверная почта
`bad_quantity`	422	Количество — целое число от 1 до 9999
`bad_status`	422	Нет такого статуса заказа
`bad_delivery`	422	Нет такого способа доставки или он выключен
`bad_payment`	422	Нет такого способа оплаты, он выключен или не подходит к выбранной доставке
`bad_order`	400	Параметр `order` — `asc` или `desc`
`item_unavailable`	422	Строгий заказ (`strict: true`): часть позиций недоступна; список — в `error.details`
`unpay_not_supported`	422	Снять отметку оплаты через API нельзя
`insufficient_stock`	409	Не хватает товара на складе для оплаты заказа; ничего не создано и не изменено
`idempotency_mismatch`	422	Этот `Idempotency-Key` уже использован с другим телом запроса
`idempotency_conflict`	409	Запрос с этим `Idempotency-Key` ещё выполняется
`order_failed`	422, 500	Не удалось создать заказ; частично созданного заказа не остаётся
`brand_failed`	500	Не удалось создать бренд
`internal_error`	500	Внутренняя ошибка, попробуйте позже
`site_unavailable`	503	Магазин недоступен
`service_unavailable`	503	Сервис временно недоступен

Ошибки адреса вебхука — в разделе «Вебхуки».

Когда повторять

429 — через Retry-After секунд.
500 и 503 — через минуту, каждый раз с паузой дольше.
409 idempotency_conflict — чуть позже, с тем же Idempotency-Key.
Остальные 4xx не повторяйте: исправьте запрос.