> ## Documentation Index
> Fetch the complete documentation index at: https://oblodai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Справочник кодов ошибок

Полный список кодов ошибок API Oblodai, сгруппированных по домену. Для каждого — HTTP‑статус, значение
и что делать. Это сводная страница для отладки: увидели код → нашли строку.

Общие правила обработки, HTTP‑классы и формат конверта ошибки — на странице
[Формат ответа и коды ошибок](/reference/basics-errors). Пошаговая диагностика по симптомам («что делать
если…») — [Что делать, если не работает](/guides/troubleshooting).

<Note>
  **Ветвитесь по `error.code`, а не по `message`.** Текст сообщения может меняться; код — контракт.
</Note>

***

## Как читать каталог

* Серый бейдж у кода — **HTTP-статус** ответа (отражает класс: `4xx` — ваша ошибка запроса, `5xx`/`503` — временная).
* **Повтор:** — это и есть краткое «что делать»: «нет — \<как исправить>» значит сначала
  поправьте запрос; «да (backoff)» — временная ошибка, повторяйте с задержкой (повтор денег‑движущих
  операций безопасен благодаря [идемпотентности](/reference/basics-idempotency) — заголовку `Idempotency-Key`
  и/или `order_id`).

Если по коду непонятно, что делать, — найдите симптом в
[хабе диагностики](/guides/troubleshooting).

***

## auth — аутентификация

<ResponseField name="auth.bad_timestamp" type="401">
  `X-Timestamp` отсутствует или не число. **Повтор:** Нет — передайте unix‑секунды.
</ResponseField>

<ResponseField name="auth.ip_not_allowed" type="401">
  IP вне включённого [IP‑allowlist](/reference/api-allowlist). **Повтор:** Нет — добавьте IP в allowlist.
</ResponseField>

<ResponseField name="merchant.bad_signature" type="401">
  Подпись не совпала или `X-Timestamp` вне окна ±5 минут. **Повтор:** Нет — проверьте подпись; синхронизируйте часы (NTP).
</ResponseField>

<ResponseField name="merchant.unknown_key" type="401">
  Неизвестный или отозванный `X-Public-Id`. **Повтор:** Нет — проверьте ключ.
</ResponseField>

<ResponseField name="merchant.wrong_key_kind" type="403">
  Только для старых **раздельных** ключей: ключ без права на этот эндпоинт. Единый API‑ключ (`oblodai_…`) подходит везде. **Повтор:** Нет — используйте единый API‑ключ.
</ResponseField>

<ResponseField name="auth.body_read" type="400">
  Сервер не смог прочитать тело запроса (обрыв соединения при отправке). **Повтор:** Да — повторите запрос.
</ResponseField>

Диагностика подписи — [Как подписать запрос](/guides/signing-requests).

***

## request — общий разбор запроса

<ResponseField name="request.bad_json" type="400">
  Тело не парсится как JSON. **Повтор:** Нет — исправьте тело.
</ResponseField>

***

## idempotency — заголовок `Idempotency-Key`

Приходят на создающих методах, если вы прислали заголовок
[`Idempotency-Key`](/reference/basics-idempotency).

<ResponseField name="idempotency.in_progress" type="409">
  Запрос с этим ключом **ещё выполняется**. Объект, возможно, уже создаётся. **Повтор:** Да (backoff) — повторите тот же запрос с тем же ключом чуть позже; получите исходный ответ.
</ResponseField>

<ResponseField name="idempotency.bad_key" type="400">
  Некорректный `Idempotency-Key` (пустой или длиннее 255 символов). **Повтор:** Нет — исправьте ключ.
</ResponseField>

<ResponseField name="idempotency.unavailable" type="503">
  Хранилище идемпотентности временно недоступно. Запрос **не выполнен** — молча продублировать операцию шлюз не станет. **Повтор:** Да (backoff) — повторите с тем же ключом.
</ResponseField>

***

## payment — приём платежей

<ResponseField name="payment.unknown_currency" type="400">
  Неизвестная `currency`. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payment.unknown_to_currency" type="400">
  Неизвестная `to_currency`. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payment.to_currency_required" type="400">
  Цена в фиате (`currency: "USD"`), задана `network`, но не задана `to_currency`: из долларов монету расчёта вывести нельзя. **Повтор:** Нет — задайте `to_currency` (монету, в которой платят) либо уберите и `network` тоже — тогда монету выберет покупатель.
</ResponseField>

<ResponseField name="payment.network_required" type="400">
  У валюты несколько сетей, `network` не задан. **Повтор:** Нет — укажите сеть.
</ResponseField>

<ResponseField name="payment.unsupported_network" type="400">
  Пара валюта+сеть не поддерживается. **Повтор:** Нет — см. [каталог](/reference/basics-networks).
</ResponseField>

<ResponseField name="payment.bad_amount" type="400">
  Некорректная сумма. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payment.bad_subtract" type="400">
  `subtract` вне 0–100. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payment.bad_accuracy" type="400">
  `accuracy_payment_percent` вне 0–5. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payment.below_minimum" type="400">
  Сумма ниже минимума сети. **Повтор:** Нет — увеличьте сумму или смените сеть.
</ResponseField>

<ResponseField name="payment.bad_url_callback" type="400">
  `url_callback` не валидный http(s)-URL (или приватный адрес). **Повтор:** Нет — исправьте URL.
</ResponseField>

<ResponseField name="payment.bad_uuid" type="400">
  Некорректный формат `uuid`. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payment.no_lookup" type="400">
  Не передан ни `uuid`, ни `order_id`. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payment.not_found" type="404">
  Счёт не найден (или скрыт как чужой). **Повтор:** Нет — проверьте идентификатор.
</ResponseField>

Методы: [`/v1/payment`](/reference/payment-create), [`/v1/payment/info`](/reference/payment-info).

***

## invoice — движок счёта

Ошибки самого движка счёта. Всплывают при создании ([`/v1/payment`](/reference/payment-create)), выборе валюты
на hosted‑странице ([`/v1/pay/{id}/select`](/reference/pay-select)) и при переоценке счёта.

<ResponseField name="invoice.bad_price" type="400">
  Некорректная сумма счёта. **Повтор:** Нет — исправьте сумму.
</ResponseField>

<ResponseField name="invoice.no_pay_asset" type="400">
  Не удалось определить актив оплаты. **Повтор:** Нет — задайте `to_currency`/`network`.
</ResponseField>

<ResponseField name="invoice.not_selectable" type="400">
  Счёт не в статусе `select` (валюта уже выбрана). **Повтор:** Нет.
</ResponseField>

<ResponseField name="invoice.expired" type="400">
  Срок счёта истёк. **Повтор:** Нет — создайте новый счёт.
</ResponseField>

<ResponseField name="invoice.generation_stale" type="409">
  Состояние счёта изменилось параллельно (reorg/гонка). **Повтор:** Да — перечитайте счёт и повторите.
</ResponseField>

<ResponseField name="invoice.quote_failed" type="503">
  Оракул курса временно недоступен. **Повтор:** Да — повторите с backoff.
</ResponseField>

<ResponseField name="invoice.fee_quote_failed" type="503">
  Не удалось оценить по курсу фиксированную часть комиссии (\$0.30 с платежа). Счёт **не создаётся** — комиссия не «обнуляется» молча. **Повтор:** Да — повторите с backoff.
</ResponseField>

<ResponseField name="invoice.address_failed" type="503">
  Не удалось выделить депозит‑адрес. **Повтор:** Да — повторите с backoff.
</ResponseField>

***

## pay — hosted‑страница оплаты

<ResponseField name="pay.bad_uuid" type="400">
  Некорректный `{id}` в пути. **Повтор:** Нет.
</ResponseField>

<ResponseField name="pay.not_found" type="404">
  Счёт не найден. **Повтор:** Нет.
</ResponseField>

<ResponseField name="pay.not_selectable" type="400">
  Валюта уже выбрана (счёт не в статусе `select`). **Повтор:** Нет.
</ResponseField>

<ResponseField name="pay.unknown_currency" type="400">
  Неизвестная валюта при выборе. **Повтор:** Нет.
</ResponseField>

<ResponseField name="pay.method_not_accepted" type="400">
  Метод не входит в набор [`accepted`](/reference/payment-accepted). **Повтор:** Нет.
</ResponseField>

<ResponseField name="pay.below_minimum" type="400">
  Сумма ниже минимума сети. **Повтор:** Нет.
</ResponseField>

Методы: [`GET /v1/pay/{id}`](/reference/pay-get), [`POST /v1/pay/{id}/select`](/reference/pay-select).

***

## wallet — статические кошельки

<ResponseField name="wallet.unknown_currency" type="400">
  Неизвестная валюта. **Повтор:** Нет.
</ResponseField>

<ResponseField name="wallet.no_network" type="400">
  Не указана сеть. **Повтор:** Нет.
</ResponseField>

<ResponseField name="wallet.unsupported_network" type="400">
  Пара валюта+сеть не поддерживается. **Повтор:** Нет.
</ResponseField>

<ResponseField name="wallet.no_address" type="400">
  Не передан `address`. **Повтор:** Нет.
</ResponseField>

<ResponseField name="wallet.bad_uuid" type="400">
  Некорректный `uuid` кошелька. **Повтор:** Нет.
</ResponseField>

<ResponseField name="wallet.static_not_found" type="404">
  Статический кошелёк не найден. **Повтор:** Нет — проверьте `uuid`.
</ResponseField>

Методы: [`/v1/wallet`](/reference/wallet-create), [`/v1/wallet/block`](/reference/wallet-block),
[`/v1/wallet/blocked-address-refund`](/reference/wallet-blocked-refund).

***

## qr — генерация QR

<ResponseField name="qr.no_address" type="400">
  Не передан `address`. **Повтор:** Нет.
</ResponseField>

Метод: [`/v1/wallet/qr`](/reference/wallet-qr).

***

## payout — выплаты

<ResponseField name="payout.unknown_currency" type="400">
  Неизвестная валюта. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payout.bad_amount" type="400">
  Некорректная сумма. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payout.order_id_required" type="400">
  Не передан `order_id`. **Повтор:** Нет — задавайте всегда.
</ResponseField>

<ResponseField name="payout.destination_internal" type="400">
  Адрес принадлежит шлюзу (self‑dealing). **Повтор:** Нет — укажите внешний адрес.
</ResponseField>

<ResponseField name="payout.no_destination" type="400">
  Не передан адрес назначения. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payout.bad_address" type="400">
  Пустой/некорректный адрес. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payout.address_network_mismatch" type="400">
  Адрес не соответствует выбранной сети. **Повтор:** Нет — проверьте сеть.
</ResponseField>

<ResponseField name="payout.asset_mismatch" type="400">
  Валюта и сеть не соответствуют друг другу. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payout.frozen" type="409">
  Выплаты заморожены (kill‑switch). **Повтор:** Да (backoff) — после снятия заморозки.
</ResponseField>

<ResponseField name="payout.from_currency_unsupported" type="400">
  Неподдерживаемая конвертация (только `USDT`→`currency`). **Повтор:** Нет.
</ResponseField>

<ResponseField name="payout.convert_same_asset" type="400">
  `from_currency` совпадает с валютой выплаты — конвертировать нечего. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payout.convert_bad_amount" type="400">
  Некорректная сумма для конвертации из `from_currency`. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payout.convert_unsupported" type="400">
  Такая конвертация не поддерживается. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payout.convert_no_rate" type="503">
  Нет курса для конвертации (оракул недоступен). **Повтор:** Да — повторите с backoff.
</ResponseField>

<ResponseField name="payout.convert_frozen" type="409">
  Конвертации временно заморожены. **Повтор:** Да (backoff) — после снятия.
</ResponseField>

<ResponseField name="payout.convert_insufficient" type="409">
  Недостаточно баланса в `from_currency` для конвертации. **Повтор:** Да, после пополнения.
</ResponseField>

<ResponseField name="payout.memo_too_long" type="400">
  `memo` длиннее 120 символов. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payout.bad_url_callback" type="400">
  Некорректный `url_callback` (SSRF). **Повтор:** Нет.
</ResponseField>

<ResponseField name="payout.amount_below_fee" type="400">
  Сумма меньше сетевой комиссии. **Повтор:** Нет — увеличьте сумму.
</ResponseField>

<ResponseField name="payout.bad_uuid" type="400">
  Некорректный `uuid`. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payout.no_lookup" type="400">
  Не передан ни `uuid`, ни `order_id`. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payout.not_found" type="404">
  Выплата не найдена (или скрыта как чужая). **Повтор:** Нет — проверьте `uuid`/`order_id`.
</ResponseField>

<ResponseField name="payout.empty_batch" type="400">
  Пустой массив `payouts` (mass). **Повтор:** Нет.
</ResponseField>

<ResponseField name="payout.batch_too_large" type="400">
  Больше 100 элементов (mass). **Повтор:** Нет — режьте на пачки.
</ResponseField>

<ResponseField name="payout.not_pending" type="409">
  Выплата не в статусе `pending` (approve). **Повтор:** Нет.
</ResponseField>

<ResponseField name="payout.approver_is_creator" type="403">
  Подтверждающий совпадает с создателем (maker‑checker). **Повтор:** Нет.
</ResponseField>

<ResponseField name="payout.insufficient_funds" type="409">
  Недостаточно доступного баланса. **Повтор:** Да, после пополнения.
</ResponseField>

<ResponseField name="payout.funds_maturing" type="409">
  Средства ещё дозревают (maturity‑холд). **Повтор:** Да (backoff) — дождитесь подтверждений.
</ResponseField>

<ResponseField name="payout.duplicate_reference" type="409">
  Гонка двух одновременных вставок с одним `reference`/`order_id`. Обычный повтор — не ошибка (вернётся уже созданная выплата). **Повтор:** Повторите — идемпотентность вернёт существующую выплату; либо сверьтесь через [`/payout/info`](/reference/payout-info).
</ResponseField>

Методы: [`/v1/payout`](/reference/payout-create), [`/v1/payout/mass`](/reference/payout-mass),
[`/v1/payout/info`](/reference/payout-info), [`/v1/payout/approve`](/reference/payout-approve).

***

## payoutlink — выплатные ссылки (крипто-чеки)

<ResponseField name="payoutlink.unknown_currency" type="400">
  Неизвестный крипто-актив. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payoutlink.bad_amount" type="400">
  Некорректная сумма. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payoutlink.insufficient_funds" type="409">
  Недостаточно доступного баланса для резерва. **Повтор:** Да, после пополнения.
</ResponseField>

<ResponseField name="payoutlink.funds_maturing" type="409">
  Средства ещё дозревают. **Повтор:** Да, позже с backoff.
</ResponseField>

<ResponseField name="payoutlink.empty_batch" type="400">
  Пустой массив `links`. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payoutlink.batch_too_large" type="400">
  Больше 500 элементов в батче ссылок. **Повтор:** Нет — разбейте на страницы.
</ResponseField>

<ResponseField name="payoutlink.bad_id" type="400">
  Некорректный `link_id`. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payoutlink.not_found" type="404">
  Ссылка не найдена (или чужая), для claim — битый токен. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payoutlink.not_funded" type="409">
  Отменить можно только невостребованную ссылку. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payoutlink.no_address" type="400">
  Claim без адреса. **Повтор:** Нет — передайте `address`.
</ResponseField>

<ResponseField name="payoutlink.destination_internal" type="400">
  Claim на внутренний адрес шлюза запрещён. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payoutlink.expired" type="409">
  Срок ссылки вышел, резерв возвращён. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payoutlink.cancelled" type="409">
  Ссылка отменена мерчантом. **Повтор:** Нет.
</ResponseField>

<ResponseField name="payoutlink.claim_in_progress" type="409">
  Получение уже идёт с другим адресом. **Повтор:** Только с первым адресом.
</ResponseField>

<ResponseField name="payoutlink.disabled" type="503">
  Функция выключена на шлюзе. **Повтор:** Нет.
</ResponseField>

## resolution — резолв недоплаты

<ResponseField name="resolution.bad_action" type="400">
  `action` не `accept`/`refund`. **Повтор:** Нет.
</ResponseField>

<ResponseField name="resolution.not_underpaid" type="409">
  Платёж не в статусе `wrong_amount`. **Повтор:** Нет — сверьтесь с `/v1/payment/info`.
</ResponseField>

<ResponseField name="resolution.already_resolved" type="409">
  Решение по счёту уже принято. **Повтор:** Нет.
</ResponseField>

<ResponseField name="resolution.already_refunded" type="409">
  По счёту уже был возврат — accept невозможен. **Повтор:** Нет.
</ResponseField>

<ResponseField name="resolution.disabled" type="503">
  Функция выключена на шлюзе. **Повтор:** Нет.
</ResponseField>

## refund — возвраты

<ResponseField name="refund.no_address" type="400">
  Не передан адрес назначения. **Повтор:** Нет.
</ResponseField>

<ResponseField name="refund.bad_amount" type="400">
  Некорректная сумма. **Повтор:** Нет.
</ResponseField>

<ResponseField name="refund.nothing_to_refund" type="400">
  Нечего возвращать. Также приходит на валюто‑агностичный счёт (`is_multi: true`), где покупатель ещё не выбрал монету: валюты расчёта нет — возвращать нечего. **Повтор:** Нет.
</ResponseField>

<ResponseField name="refund.destination_internal" type="400">
  Адрес назначения принадлежит шлюзу. **Повтор:** Нет.
</ResponseField>

<ResponseField name="refund.dust" type="400">
  Сумма слишком мала (dust). **Повтор:** Нет.
</ResponseField>

<ResponseField name="refund.exceeds_refundable" type="400">
  Больше оплаченной суммы вернуть нельзя. **Повтор:** Нет.
</ResponseField>

<ResponseField name="refund.exceeds_excess" type="400">
  Возврат переплаты превышает саму переплату. **Повтор:** Нет.
</ResponseField>

<ResponseField name="refund.reference_collision" type="409">
  Тот же `(платёж, адрес, сумма)` уже в работе. **Повтор:** Нет — это идемпотентность.
</ResponseField>

Методы: [`/v1/payment/refund`](/reference/payment-refund),
[`/v1/wallet/blocked-address-refund`](/reference/wallet-blocked-refund).

***

## batch — массовые операции

Ошибки **уровня батча** (весь запрос отклонён). Ошибки отдельных элементов приходят не сюда, а в
`items[].error` ответа [`/v1/batch/info`](/reference/batch-info) — там это коды соответствующего домена
(`payment.*`, `refund.*`, `payout.*`).

<ResponseField name="batch.empty" type="400">
  Массив элементов (`payments` / `refunds` / `payouts`) пуст. **Повтор:** Нет — добавьте элементы.
</ResponseField>

<ResponseField name="batch.too_large" type="400">
  Больше **5000** элементов в одном батче. **Повтор:** Нет — разбейте на несколько батчей.
</ResponseField>

<ResponseField name="batch.bad_id" type="400">
  `batch_id` не является корректным UUID. **Повтор:** Нет — проверьте идентификатор.
</ResponseField>

<ResponseField name="batch.not_found" type="404">
  Батч не найден (или принадлежит другому мерчанту). **Повтор:** Нет.
</ResponseField>

<ResponseField name="batch.disabled" type="503">
  Массовая обработка недоступна на этом шлюзе. **Повтор:** Да (backoff) — либо отправляйте операции по одной.
</ResponseField>

Методы: [`/v1/payment/batch`](/reference/payment-batch), [`/v1/refund/batch`](/reference/refund-batch),
[`/v1/payout/batch`](/reference/payout-batch), [`/v1/batch/info`](/reference/batch-info).

***

## paylink — платёжные ссылки

Часть кодов приходит вам (при создании ссылки), часть — покупателю (при оплате по ссылке).

<ResponseField name="paylink.bad_id" type="400">
  `link_id` / `{id}` не является корректным UUID. **Повтор:** Нет.
</ResponseField>

<ResponseField name="paylink.not_found" type="404">
  Ссылка не найдена, выключена или истекла. **Повтор:** Нет — проверьте `link_id` или включите ссылку через `/toggle`.
</ResponseField>

<ResponseField name="paylink.bad_mode" type="400">
  `amount_mode` не `fixed` / `open` / `range`. **Повтор:** Нет — исправьте режим.
</ResponseField>

<ResponseField name="paylink.unknown_currency" type="400">
  Неизвестная валюта ссылки. **Повтор:** Нет — см. `pricing_currencies` в [`/v1/currencies`](/reference/currencies).
</ResponseField>

<ResponseField name="paylink.bad_amount" type="400">
  `amount_fixed` не положительное число (режим `fixed`). **Повтор:** Нет.
</ResponseField>

<ResponseField name="paylink.bad_min" type="400">
  `amount_min` не положительное число. **Повтор:** Нет.
</ResponseField>

<ResponseField name="paylink.bad_max" type="400">
  `amount_max` не положительное число. **Повтор:** Нет.
</ResponseField>

<ResponseField name="paylink.bad_range" type="400">
  `amount_min` больше `amount_max`. **Повтор:** Нет.
</ResponseField>

<ResponseField name="paylink.amount_required" type="400">
  Режим `open`/`range`, а покупатель не ввёл сумму. **Повтор:** Нет — покажите покупателю поле ввода суммы.
</ResponseField>

<ResponseField name="paylink.not_positive" type="400">
  Введённая сумма не положительная. **Повтор:** Нет.
</ResponseField>

<ResponseField name="paylink.below_min" type="400">
  Введённая сумма меньше `amount_min`. **Повтор:** Нет — покажите покупателю минимум.
</ResponseField>

<ResponseField name="paylink.above_max" type="400">
  Введённая сумма больше `amount_max`. **Повтор:** Нет — покажите покупателю максимум.
</ResponseField>

<ResponseField name="paylink.disabled" type="503">
  Платёжные ссылки недоступны на этом шлюзе. **Повтор:** Да (backoff).
</ResponseField>

Методы: [`/v1/payment/link` и др.](/reference/payment-link), [`GET /v1/link/{id}` · `/checkout`](/reference/link-public).

При оплате по ссылке может прийти **любая ошибка создания счёта** (`payment.*`, `invoice.*`) —
checkout проходит тот же путь, что и [`POST /v1/payment`](/reference/payment-create).

***

## split — сплит‑платежи

<ResponseField name="split.bad_destination" type="400">
  Получатель не задан либо заданы **оба** (`address` и `merchant_id`). **Повтор:** Нет — задайте ровно один вариант.
</ResponseField>

<ResponseField name="split.network_required" type="400">
  Задан `address`, но не задана `network`. **Повтор:** Нет — укажите сеть.
</ResponseField>

<ResponseField name="split.bad_percent" type="400">
  `percent` вне диапазона 0–100. **Повтор:** Нет.
</ResponseField>

<ResponseField name="split.exceeds_100" type="400">
  Сумма долей всех правил превысила 100 %. **Повтор:** Нет — уменьшите доли или удалите правило.
</ResponseField>

<ResponseField name="split.bad_merchant" type="400">
  `merchant_id` не является корректным UUID. **Повтор:** Нет.
</ResponseField>

<ResponseField name="split.self_destination" type="400">
  Получатель сплита — вы сами. **Повтор:** Нет — укажите другого получателя.
</ResponseField>

<ResponseField name="split.bad_hold" type="400">
  `refund_hold_hours` вне диапазона 0–2160 (90 суток). **Повтор:** Нет.
</ResponseField>

<ResponseField name="split.bad_id" type="400">
  `rule_id` не является корректным UUID. **Повтор:** Нет.
</ResponseField>

<ResponseField name="split.not_found" type="404">
  Правило не найдено. **Повтор:** Нет.
</ResponseField>

<ResponseField name="split.disabled" type="503">
  Сплит‑платежи недоступны на этом шлюзе. **Повтор:** Да (backoff).
</ResponseField>

Методы: [`/v1/split/rule*`](/reference/split-rule), [`/v1/split/config/*`](/reference/split-config).

***

## email — письма покупателю

<ResponseField name="email.no_recipient" type="400">
  Получатель не определён: не передан `email` и у платежа нет `payer_email`. **Повтор:** Нет — передайте `email` либо задавайте `payer_email` при создании счёта.
</ResponseField>

<ResponseField name="email.disabled" type="503">
  Почта не настроена на этом шлюзе. **Повтор:** Да (backoff) — либо шлите письмо сами.
</ResponseField>

Метод: [`/v1/payment/send-email`](/reference/payment-send-email).

***

## compliance — AML‑проверка

Если у шлюза включён комплаенс‑провайдер, адрес назначения выплаты/возврата проверяется перед отправкой.

<ResponseField name="compliance.blocked" type="403">
  Адрес назначения заблокирован AML‑проверкой. **Повтор:** Нет — используйте другой адрес.
</ResponseField>

<ResponseField name="compliance.no_destination" type="400">
  Для проверки не передан адрес назначения. **Повтор:** Нет.
</ResponseField>

Методы: [`/v1/payout`](/reference/payout-create), [`/v1/payment/refund`](/reference/payment-refund),
[`/v1/wallet/blocked-address-refund`](/reference/wallet-blocked-refund).

***

## transfer — перевод на личный кошелёк

<ResponseField name="transfer.no_personal_wallet" type="400">
  У мерчанта нет привязанного владельца. **Повтор:** Нет.
</ResponseField>

<ResponseField name="transfer.unknown_currency" type="400">
  Неизвестная валюта. **Повтор:** Нет.
</ResponseField>

<ResponseField name="transfer.bad_amount" type="400">
  Некорректная сумма. **Повтор:** Нет.
</ResponseField>

<ResponseField name="personal.amount_invalid" type="400">
  Сумма перевода некорректна (≤0 или неверный формат). **Повтор:** Нет.
</ResponseField>

<ResponseField name="personal.insufficient" type="400">
  Недостаточно средств на балансе для перевода. **Повтор:** Да, после пополнения.
</ResponseField>

Метод: [`/v1/transfer/to-personal`](/reference/transfer-to-personal).

***

## Настройки приёма

### accepted — принимаемые валюты

<ResponseField name="accepted.unknown_currency" type="400">
  Неизвестная валюта в наборе. **Повтор:** Нет — исправьте валюту.
</ResponseField>

<ResponseField name="accepted.no_network" type="400">
  Не указана сеть для элемента. **Повтор:** Нет — укажите сеть.
</ResponseField>

### discount — скидки/наценки

<ResponseField name="discount.unknown_currency" type="400">
  Неизвестная валюта. **Повтор:** Нет — исправьте валюту.
</ResponseField>

<ResponseField name="discount.out_of_range" type="400">
  `discount_percent` вне −99…99. **Повтор:** Нет — задайте значение в диапазоне.
</ResponseField>

### accuracy — допуск недоплаты

<ResponseField name="accuracy.out_of_range" type="400">
  При `enabled: true` значение `accuracy_percent` вне 1–5 %. **Повтор:** Нет — задайте значение 1–5 %.
</ResponseField>

### vrcs

<ResponseField name="vrcs.read" type="400">
  Ошибка чтения состояния VRCS. **Повтор:** Да (backoff) — повторите позже.
</ResponseField>

***

## Вебхуки, автовывод, allowlist

### webhook

<ResponseField name="webhook.no_url" type="400">
  Не передан `url` / `url_callback`. **Повтор:** Нет — передайте URL.
</ResponseField>

<ResponseField name="webhook.bad_url" type="400">
  Некорректный или запрещённый (приватный/локальный) URL. **Повтор:** Нет — исправьте URL.
</ResponseField>

<ResponseField name="webhook.test_failed" type="503">
  Ваш эндпоинт не принял пробное тело. **Повтор:** Да (backoff) — после починки эндпоинта.
</ResponseField>

### autowithdraw

<ResponseField name="autowithdraw.unknown_currency" type="400">
  Неизвестный актив. **Повтор:** Нет — исправьте актив.
</ResponseField>

<ResponseField name="autowithdraw.bad_min" type="400">
  Некорректный порог. **Повтор:** Нет — исправьте порог.
</ResponseField>

<ResponseField name="autowithdraw.missing" type="400">
  Не хватает обязательного поля. **Повтор:** Нет — добавьте поле.
</ResponseField>

При `set` адрес также проходит валидацию сети — возможны `payout.bad_address` и
`payout.address_network_mismatch` (см. раздел payout).

### apiallow — IP‑allowlist

<ResponseField name="apiallow.bad_cidr" type="400">
  Некорректный IP или CIDR. **Повтор:** Нет — исправьте IP/CIDR.
</ResponseField>

<ResponseField name="apiallow.empty" type="400">
  Нельзя включить контроль с пустым списком. **Повтор:** Нет — добавьте хотя бы один адрес.
</ResponseField>

***

## Общие серверные ошибки

| HTTP | Класс         | Значение                                                                                                 |
| ---- | ------------- | -------------------------------------------------------------------------------------------------------- |
| 429  | rate limit    | Превышен лимит частоты. В ответе — `Retry-After: 60`. См. [лимиты частоты](/reference/basics-ratelimit). |
| 503  | `unavailable` | Временная недоступность зависимости (напр. оракул курсов).                                               |
| 500  | `internal`    | Внутренняя ошибка, детали не раскрываются.                                                               |

Все три ошибки транзиентны — повторяйте с backoff; для 429 дождитесь `Retry-After`.

<Note>
  **Транзиентные коды с HTTP 503.** Кроме перечисленных выше, при недоступности зависимостей могут
  прийти доменные коды класса 503 — например `rates.no_source` / `rates.non_positive` / `rates.deviation`
  (курс), `payout.freeze_unknown` (хранилище kill‑switch), `ledger.unavailable` (учёт). Все они —
  **временные**: повторяйте тот же идемпотентный запрос с backoff.
</Note>

***

## Связанные страницы

<CardGroup cols={2}>
  <Card title="Формат ответа и коды ошибок" href="/reference/basics-errors" icon="arrow-right" horizontal>
    HTTP‑классы и правила обработки.
  </Card>

  <Card title="FAQ и устранение неполадок" href="/guides/faq-troubleshooting" icon="arrow-right" horizontal>
    что делать при частых ошибках.
  </Card>

  <Card title="Глоссарий" href="/reference/glossary" icon="arrow-right" horizontal>
    термины, встречающиеся в описаниях.
  </Card>
</CardGroup>