Ошибки

Публичный API отвечает обычными кодами HTTP. Ниже — что каждый из них означает на практике и когда запрос имеет смысл повторить.

Успешные ответы

Код	Когда
201	Платёж создан этим запросом.
200	Платёж с таким external_order_id в этом проекте уже был — вернули существующий. Это не ошибка: повтор запроса безопасен по построению.

Ошибки

Код	Причина	Что делать
401	Нет заголовка Authorization, он не в формате Bearer …, либо ключ неизвестен, отозван или принадлежит архивному проекту.	Не повторять. Все перечисленные случаи отвечают одинаково — по ответу нельзя выяснить, существует ли такой ключ. Проверьте ключ в кабинете.
404	Платёж не найден — или не существует, или принадлежит другому проекту.	Не повторять. Убедитесь, что запрашиваете платёж ключом того же проекта, которым он был создан.
409	Гонка: два одновременных первых создания с одним external_order_id. Встречается редко.	Повторить один раз — победивший запрос уже создал платёж, и повтор вернёт его с кодом 200.
422	Поля не прошли проверку: отсутствует обязательное, amount не больше нуля или с более чем двумя знаками после запятой, строка длиннее допустимого, return_url/fail_url не являются адресами.	Не повторять без изменений — тело ответа перечисляет конкретные поля.
422 amount_above_maximum	Сумма выше потолка платежа, и криптовалюта, на которую потолок не распространяется, недоступна — оплатить такой платёж было бы нечем. В теле приходит max_rub.	Не повторять с той же суммой: разбейте платёж или уменьшите его.
5xx	Сбой на нашей стороне.	Повторить с выдержкой. Создание платежа идемпотентно по external_order_id, поэтому повтор не создаст второй платёж.

Отказы на странице оплаты

Это то, что видит плательщик; вашему серверу они приходят не как ошибка запроса, а как смена статуса платежа в webhook.

• Отказ эквайера — платёж переходит в declined. Причину банк не раскрывает, плательщику показывается общее сообщение. Повторная попытка возможна только новым платежом.
• Процессор недоступен — оплата не начинается, платёж остаётся в pending до истечения срока. Плательщик может попробовать снова или выбрать другой способ.
• Истёк срок — платёж переходит в expired. Оплатить его больше нельзя, нужен новый.

Правило повторов

Повторять стоит только 5xx и 409. Ответы 401, 404 и 422 при повторе дадут ровно то же самое — их надо чинить, а не ретраить.

Поскольку создание идемпотентно, самый безопасный сценарий после сетевого таймаута — повторить тот же запрос с тем же external_order_id. Придумывать новый идентификатор заказа для повтора не нужно и вредно: так вместо одного платежа получатся два.