Отличия Sandbox от документации

Справочник для разработчика магазина и инженера поддержки: где ответы API в тестовой среде (Sandbox) расходятся с документацией Яндекс Пэй или описывают то, чего в ней нет. По таблице можно понять, какие ветки обработки ошибок в коде магазина не сработают и что проверить при разборе обращения.

Что проверено

Каждая строка подтверждена запросом в Sandbox 11–12 октября 2026 года, ссылка ведёт на лог. Поведение в Production не проверялось и может отличаться. Коды ошибок с причинами и рекомендациями — в справочнике Коды ошибок.

Возврат — POST /v2/orders/{order_id}/refund

Источник: описание метода возврата.

Ситуация	В документации	В Sandbox	Что это значит	Лог
Повтор возврата с тем же externalOperationId после того, как возврат запущен	«Если процесс возврата был успешно запущен, то повторный вызов метода возврата с тем же externalOperationId вернет ошибку» DUPLICATE_EXTERNAL_OPERATION_ID	200 и та же операция (тот же operationId) с текущим статусом, в том числе после перехода в SUCCESS. Ошибка не приходит	Ветка обработки DUPLICATE_EXTERNAL_OPERATION_ID в коде магазина не сработает. Повтор с тем же externalOperationId безопасен: второй возврат не создаётся. Повтор с новым externalOperationId проводит второй возврат	10, 11
refundAmount больше остатка заказа	REFUND_AMOUNT_TOO_LARGE	REFUND_AMOUNT_EXPECTATION_FAILED — и с корзиной (1 000 000,00 ₽ при заказе на 39 000,00 ₽), и без неё (10 000,00 ₽ при остатке 3 000,00 ₽)	Обработчик REFUND_AMOUNT_TOO_LARGE не сработает. Сумму, которую ожидает API, сервер показывает в details.actual_refund_amount	07, шаги 2–3
refundAmount = 0.00 вместе с refundCart	REFUND_AMOUNT_TOO_SMALL (меньше 1 рубля) или REFUND_NOT_POSITIVE_AMOUNT	REFUND_AMOUNT_EXPECTATION_FAILED: сумма сверяется с корзиной раньше, чем проверяется на минимум. Без корзины не проверялось	Ошибка про сумму почти всегда приходит как REFUND_AMOUNT_EXPECTATION_FAILED. Причину видно по details	07, шаг 1
Возврат без targetCart и refundCart	Возвращается вся корзина. В списке ошибок есть ORDER_CART_EMPTY — не передана ни одна корзина	ORDER_CART_EMPTY не приходит. Запрос считается возвратом остатка заказа: refundAmount сверяется с суммой, которая осталась после прошлых возвратов	Чтобы вернуть остаток после частичных возвратов, передайте только refundAmount, равный остатку. Сумма больше остатка даёт REFUND_AMOUNT_EXPECTATION_FAILED, сумма меньше остатка не проверялась	07, шаг 3
В refundCart передана позиция, которая уже возвращена целиком	productId — идентификатор позиции из исходной корзины. Неизвестный идентификатор вызывает ORDERUPDATE_UNKNOWN_ITEM_PRODUCT_ID	Сервер сверяет productId с текущей корзиной. Возвращённая позиция из неё удалена и считается неизвестной, хотя в тексте ошибки написано «not present in the original cart»	Партнёр видит «товара нет в корзине», хотя товар был в заказе. Проверьте, не возвращена ли позиция раньше: GET /v1/orders/{order_id} → operations и cart.items	09
Возврат по заказу в статусе REFUNDED	Возврат возможен, если paymentStatus — CAPTURED или PARTIALLY_REFUNDED	INVALID_PAYMENT_STATUS, в details.expected кроме этих двух статусов есть AUTHORIZED	Возможно, возврат допустим и для заказа, который только авторизован. Не проверялось	08
В запросе поле с опечаткой в имени: targerCart вместо targetCart вместе с refundCart	Не описано	Неизвестное поле сервер молча игнорирует. Возврат прошёл по refundCart, хотя с правильным именем поля запрос вернул бы REFUND_ONLY_ONE_CART_EXPECTATION_FAILED	Опечатка в имени поля не даёт ошибки, а меняет смысл запроса. При разборе обращения сверяйте имена полей с документацией посимвольно	12, для сравнения 06

Создание заказа — POST /v1/orders

Источник: описание метода создания заказа.

Ситуация	В документации	В Sandbox	Что это значит	Лог
total позиции не равен quantity.count × discountedUnitPrice	Код не описан. Описан только ORDER_CART_DATA_ERROR: цена за единицу (total / quantity.count) должна иметь не больше двух знаков после запятой	CART_ITEM_PRICE_MISMATCH, в details — cart_item_total, cart_item_quantity и cart_item_price	В обработку ошибок создания заказа добавьте CART_ITEM_PRICE_MISMATCH. Частая причина — total посчитан по цене до скидки	02
Цена за единицу с тремя знаками после запятой	ORDER_CART_DATA_ERROR	Если цена передана в discountedUnitPrice и не сходится с total, приходит CART_ITEM_PRICE_MISMATCH. ORDER_CART_DATA_ERROR приходит, когда цены в позиции нет и сервер вычисляет её как total / quantity.count	Обе ошибки означают проблему с ценой позиции. Какая придёт, зависит от того, передана ли цена явно	03, 04