Ошибки и коды

Отказ — это статус и стабильный code:

{ "status": 409, "code": "idempotency_conflict" }

Решайте по code, а не по тексту. В рамках v1 могут появиться новые коды: незнакомый код обрабатывайте по его статусу — 4xx: исправьте запрос; 5xx: повторите с тем же Idempotency-Key.

Некоторые ответы приходят от HTTP-слоя ещё до чтения запроса, в виде application/problem+json {title, status, detail}: любой 401, 400 request body is required (команда отправлена без тела), 413 (тело больше лимита) и 422 validation failed (limit — не число). На неизвестный путь приходит простой 404, на неверный метод — 405.

Коды

Код	Статус	Значение	Что делать
authentication failed	401	Ключ неизвестен, отозван или приостановлен; неверны подпись, хеш тела или метка времени (±5 мин); или nonce уже использован. Один ответ на все случаи.	Проверьте подпись. Подписывайте каждый повтор заново.
rate_limited	429	Больше 100 запросов за эту секунду для ключа. Ничего не выполнено.	Подождите Retry-After, повторите с тем же ключом.
invalid_request	400	Тело или параметр не соответствуют API: неизвестное поле, неверный тип, сумма не с двумя знаками после точки, нет Idempotency-Key, тело там, где оно не принимается.	Исправьте запрос.
idempotency_conflict	409	Idempotency-Key, merchant_order_id или merchant_payout_id уже относится к запросу с другим телом.	Новый ключ для нового запроса.
currency_unavailable	422	Ни один провайдер не принимает эту валюту.	Используйте LKR.
method_unavailable	422	payment_method указывает метод или банк, которых нет в предложении.	Укажите метод и банк из списка, other или ничего.
payment_not_found	404	Такого платежа в этом проекте нет.	Проверьте id.
payment_not_cancellable	409	Оплачен, завершён или на проверке.	Прочитайте его; после succeeded — оформите возврат.
payment_busy	409	Идёт другое изменение платежа. Содержит Retry-After: 1.	Повторите после паузы с тем же ключом.
payment_version_conflict	409	Корректировка указывает версию, из которой платёж уже вышел.	Прочитайте платёж и корректируйте по его текущей версии.
payment_not_correctable	409	Платёж не ждёт денег.	Отмените и создайте новый.
amount_unchanged	409	Корректировка указывает текущую сумму.	Ничего делать не нужно.
payment_not_refundable	409	Не succeeded, или его провайдер не умеет возвраты.	Возвращайте только успешные платежи.
refund_exceeds_payment	422	Больше полученного за вычетом уже возвращённого и возвратов в пути.	Возвращайте не больше остатка.
insufficient_available_balance	422	Возврат или выплата с комиссией превышает available. Ничего не удержано.	Дождитесь зачислений или уменьшите сумму.
payment_unavailable	503	Результат неизвестен.	Повторите с тем же ключом или прочитайте платёж.
payout_method_unavailable	422	Для вашего проекта не задана ставка выплат.	Обратитесь к вашему менеджеру.
payout_not_found	404	Такой выплаты в этом проекте нет.	Проверьте id.
payout_not_cancellable	409	Агент её взял, или она завершена.	Дождитесь результата.
payout_unavailable	503	Результат неизвестен.	Повторите с тем же ключом или GET /v1/payouts?merchant_payout_id=.
balance_unavailable	503	Не удалось прочитать баланс.	Повторите.
endpoint_not_found	404	Эндпоинт вебхуков не задан.	Сначала PUT /v1/webhook-endpoint.
url_not_allowed	422	Не HTTPS на публичный хост с именем на порту 443 или 8443.	Используйте публичный HTTPS-адрес.
endpoint_disabled	409	Тест выключенного эндпоинта.	Сначала включите его.
delivery_not_found	404	Такой доставки нет, или неверный cursor.	Проверьте id; начните список заново.
delivery_not_retryable	409	Доставка ещё идёт по расписанию.	Дождитесь, пока она будет доставлена или завершится неудачей.
webhooks_unavailable	503	Настройки вебхуков сейчас недоступны.	Повторите.
read_only	503	Техобслуживание: обслуживаются только чтения. Тело {code, message, request_id, retryable}, с Retry-After.	Повторите после паузы.