Skip to main content
Полный список кодов ошибок API Oblodai, сгруппированных по домену. Для каждого — HTTP‑статус, значение и что делать. Это сводная страница для отладки: увидели код → нашли строку. Общие правила обработки, HTTP‑классы и формат конверта ошибки — на странице Формат ответа и коды ошибок. Пошаговая диагностика по симптомам («что делать если…») — Что делать, если не работает.
Ветвитесь по error.code, а не по message. Текст сообщения может меняться; код — контракт.

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

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

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

​
401
X-Timestamp отсутствует или не число. Повтор: Нет — передайте unix‑секунды.
​
401
IP вне включённого IP‑allowlist. Повтор: Нет — добавьте IP в allowlist.
​
401
Подпись не совпала или X-Timestamp вне окна ±5 минут. Повтор: Нет — проверьте подпись; синхронизируйте часы (NTP).
​
401
Неизвестный или отозванный X-Public-Id. Повтор: Нет — проверьте ключ.
​
403
Только для старых раздельных ключей: ключ без права на этот эндпоинт. Единый API‑ключ (oblodai_…) подходит везде. Повтор: Нет — используйте единый API‑ключ.
​
400
Сервер не смог прочитать тело запроса (обрыв соединения при отправке). Повтор: Да — повторите запрос.
Диагностика подписи — Как подписать запрос.

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

​
400
Тело не парсится как JSON. Повтор: Нет — исправьте тело.

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

Приходят на создающих методах, если вы прислали заголовок Idempotency-Key.
​
409
Запрос с этим ключом ещё выполняется. Объект, возможно, уже создаётся. Повтор: Да (backoff) — повторите тот же запрос с тем же ключом чуть позже; получите исходный ответ.
​
400
Некорректный Idempotency-Key (пустой или длиннее 255 символов). Повтор: Нет — исправьте ключ.
​
503
Хранилище идемпотентности временно недоступно. Запрос не выполнен — молча продублировать операцию шлюз не станет. Повтор: Да (backoff) — повторите с тем же ключом.

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

​
400
Неизвестная currency. Повтор: Нет.
​
400
Неизвестная to_currency. Повтор: Нет.
​
400
Цена в фиате (currency: "USD"), задана network, но не задана to_currency: из долларов монету расчёта вывести нельзя. Повтор: Нет — задайте to_currency (монету, в которой платят) либо уберите и network тоже — тогда монету выберет покупатель.
​
400
У валюты несколько сетей, network не задан. Повтор: Нет — укажите сеть.
​
400
Пара валюта+сеть не поддерживается. Повтор: Нет — см. каталог.
​
400
Некорректная сумма. Повтор: Нет.
​
400
subtract вне 0–100. Повтор: Нет.
​
400
accuracy_payment_percent вне 0–5. Повтор: Нет.
​
400
Сумма ниже минимума сети. Повтор: Нет — увеличьте сумму или смените сеть.
​
400
url_callback не валидный http(s)-URL (или приватный адрес). Повтор: Нет — исправьте URL.
​
400
Некорректный формат uuid. Повтор: Нет.
​
400
Не передан ни uuid, ни order_id. Повтор: Нет.
​
404
Счёт не найден (или скрыт как чужой). Повтор: Нет — проверьте идентификатор.
Методы: /v1/payment, /v1/payment/info.

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

Ошибки самого движка счёта. Всплывают при создании (/v1/payment), выборе валюты на hosted‑странице (/v1/pay/{id}/select) и при переоценке счёта.
​
400
Некорректная сумма счёта. Повтор: Нет — исправьте сумму.
​
400
Не удалось определить актив оплаты. Повтор: Нет — задайте to_currency/network.
​
400
Счёт не в статусе select (валюта уже выбрана). Повтор: Нет.
​
400
Срок счёта истёк. Повтор: Нет — создайте новый счёт.
​
409
Состояние счёта изменилось параллельно (reorg/гонка). Повтор: Да — перечитайте счёт и повторите.
​
503
Оракул курса временно недоступен. Повтор: Да — повторите с backoff.
​
503
Не удалось оценить по курсу фиксированную часть комиссии ($0.30 с платежа). Счёт не создаётся — комиссия не «обнуляется» молча. Повтор: Да — повторите с backoff.
​
503
Не удалось выделить депозит‑адрес. Повтор: Да — повторите с backoff.

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

​
400
Некорректный {id} в пути. Повтор: Нет.
​
404
Счёт не найден. Повтор: Нет.
​
400
Валюта уже выбрана (счёт не в статусе select). Повтор: Нет.
​
400
Неизвестная валюта при выборе. Повтор: Нет.
​
400
Метод не входит в набор accepted. Повтор: Нет.
​
400
Сумма ниже минимума сети. Повтор: Нет.
Методы: GET /v1/pay/{id}, POST /v1/pay/{id}/select.

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

​
400
Неизвестная валюта. Повтор: Нет.
​
400
Не указана сеть. Повтор: Нет.
​
400
Пара валюта+сеть не поддерживается. Повтор: Нет.
​
400
Не передан address. Повтор: Нет.
​
400
Некорректный uuid кошелька. Повтор: Нет.
​
404
Статический кошелёк не найден. Повтор: Нет — проверьте uuid.
Методы: /v1/wallet, /v1/wallet/block, /v1/wallet/blocked-address-refund.

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

​
400
Не передан address. Повтор: Нет.
Метод: /v1/wallet/qr.

​
payout — выплаты

​
400
Неизвестная валюта. Повтор: Нет.
​
400
Некорректная сумма. Повтор: Нет.
​
400
Не передан order_id. Повтор: Нет — задавайте всегда.
​
400
Адрес принадлежит шлюзу (self‑dealing). Повтор: Нет — укажите внешний адрес.
​
400
Не передан адрес назначения. Повтор: Нет.
​
400
Пустой/некорректный адрес. Повтор: Нет.
​
400
Адрес не соответствует выбранной сети. Повтор: Нет — проверьте сеть.
​
400
Валюта и сеть не соответствуют друг другу. Повтор: Нет.
​
409
Выплаты заморожены (kill‑switch). Повтор: Да (backoff) — после снятия заморозки.
​
400
Неподдерживаемая конвертация (только USDT→currency). Повтор: Нет.
​
400
from_currency совпадает с валютой выплаты — конвертировать нечего. Повтор: Нет.
​
400
Некорректная сумма для конвертации из from_currency. Повтор: Нет.
​
400
Такая конвертация не поддерживается. Повтор: Нет.
​
503
Нет курса для конвертации (оракул недоступен). Повтор: Да — повторите с backoff.
​
409
Конвертации временно заморожены. Повтор: Да (backoff) — после снятия.
​
409
Недостаточно баланса в from_currency для конвертации. Повтор: Да, после пополнения.
​
400
memo длиннее 120 символов. Повтор: Нет.
​
400
Некорректный url_callback (SSRF). Повтор: Нет.
​
400
Сумма меньше сетевой комиссии. Повтор: Нет — увеличьте сумму.
​
400
Некорректный uuid. Повтор: Нет.
​
400
Не передан ни uuid, ни order_id. Повтор: Нет.
​
404
Выплата не найдена (или скрыта как чужая). Повтор: Нет — проверьте uuid/order_id.
​
400
Пустой массив payouts (mass). Повтор: Нет.
​
400
Больше 100 элементов (mass). Повтор: Нет — режьте на пачки.
​
409
Выплата не в статусе pending (approve). Повтор: Нет.
​
403
Подтверждающий совпадает с создателем (maker‑checker). Повтор: Нет.
​
409
Недостаточно доступного баланса. Повтор: Да, после пополнения.
​
409
Средства ещё дозревают (maturity‑холд). Повтор: Да (backoff) — дождитесь подтверждений.
​
409
Гонка двух одновременных вставок с одним reference/order_id. Обычный повтор — не ошибка (вернётся уже созданная выплата). Повтор: Повторите — идемпотентность вернёт существующую выплату; либо сверьтесь через /payout/info.
Методы: /v1/payout, /v1/payout/mass, /v1/payout/info, /v1/payout/approve.
​
400
Неизвестный крипто-актив. Повтор: Нет.
​
400
Некорректная сумма. Повтор: Нет.
​
409
Недостаточно доступного баланса для резерва. Повтор: Да, после пополнения.
​
409
Средства ещё дозревают. Повтор: Да, позже с backoff.
​
400
Пустой массив links. Повтор: Нет.
​
400
Больше 500 элементов в батче ссылок. Повтор: Нет — разбейте на страницы.
​
400
Некорректный link_id. Повтор: Нет.
​
404
Ссылка не найдена (или чужая), для claim — битый токен. Повтор: Нет.
​
409
Отменить можно только невостребованную ссылку. Повтор: Нет.
​
400
Claim без адреса. Повтор: Нет — передайте address.
​
400
Claim на внутренний адрес шлюза запрещён. Повтор: Нет.
​
409
Срок ссылки вышел, резерв возвращён. Повтор: Нет.
​
409
Ссылка отменена мерчантом. Повтор: Нет.
​
409
Получение уже идёт с другим адресом. Повтор: Только с первым адресом.
​
503
Функция выключена на шлюзе. Повтор: Нет.

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

​
400
action не accept/refund. Повтор: Нет.
​
409
Платёж не в статусе wrong_amount. Повтор: Нет — сверьтесь с /v1/payment/info.
​
409
Решение по счёту уже принято. Повтор: Нет.
​
409
По счёту уже был возврат — accept невозможен. Повтор: Нет.
​
503
Функция выключена на шлюзе. Повтор: Нет.

​
refund — возвраты

​
400
Не передан адрес назначения. Повтор: Нет.
​
400
Некорректная сумма. Повтор: Нет.
​
400
Нечего возвращать. Также приходит на валюто‑агностичный счёт (is_multi: true), где покупатель ещё не выбрал монету: валюты расчёта нет — возвращать нечего. Повтор: Нет.
​
400
Адрес назначения принадлежит шлюзу. Повтор: Нет.
​
400
Сумма слишком мала (dust). Повтор: Нет.
​
400
Больше оплаченной суммы вернуть нельзя. Повтор: Нет.
​
400
Возврат переплаты превышает саму переплату. Повтор: Нет.
​
409
Тот же (платёж, адрес, сумма) уже в работе. Повтор: Нет — это идемпотентность.
Методы: /v1/payment/refund, /v1/wallet/blocked-address-refund.

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

Ошибки уровня батча (весь запрос отклонён). Ошибки отдельных элементов приходят не сюда, а в items[].error ответа /v1/batch/info — там это коды соответствующего домена (payment.*, refund.*, payout.*).
​
400
Массив элементов (payments / refunds / payouts) пуст. Повтор: Нет — добавьте элементы.
​
400
Больше 5000 элементов в одном батче. Повтор: Нет — разбейте на несколько батчей.
​
400
batch_id не является корректным UUID. Повтор: Нет — проверьте идентификатор.
​
404
Батч не найден (или принадлежит другому мерчанту). Повтор: Нет.
​
503
Массовая обработка недоступна на этом шлюзе. Повтор: Да (backoff) — либо отправляйте операции по одной.
Методы: /v1/payment/batch, /v1/refund/batch, /v1/payout/batch, /v1/batch/info.
Часть кодов приходит вам (при создании ссылки), часть — покупателю (при оплате по ссылке).
​
400
link_id / {id} не является корректным UUID. Повтор: Нет.
​
404
Ссылка не найдена, выключена или истекла. Повтор: Нет — проверьте link_id или включите ссылку через /toggle.
​
400
amount_mode не fixed / open / range. Повтор: Нет — исправьте режим.
​
400
Неизвестная валюта ссылки. Повтор: Нет — см. pricing_currencies в /v1/currencies.
​
400
amount_fixed не положительное число (режим fixed). Повтор: Нет.
​
400
amount_min не положительное число. Повтор: Нет.
​
400
amount_max не положительное число. Повтор: Нет.
​
400
amount_min больше amount_max. Повтор: Нет.
​
400
Режим open/range, а покупатель не ввёл сумму. Повтор: Нет — покажите покупателю поле ввода суммы.
​
400
Введённая сумма не положительная. Повтор: Нет.
​
400
Введённая сумма меньше amount_min. Повтор: Нет — покажите покупателю минимум.
​
400
Введённая сумма больше amount_max. Повтор: Нет — покажите покупателю максимум.
​
503
Платёжные ссылки недоступны на этом шлюзе. Повтор: Да (backoff).
Методы: /v1/payment/link и др., GET /v1/link/{id} · /checkout. При оплате по ссылке может прийти любая ошибка создания счёта (payment.*, invoice.*) — checkout проходит тот же путь, что и POST /v1/payment.

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

​
400
Получатель не задан либо заданы оба (address и merchant_id). Повтор: Нет — задайте ровно один вариант.
​
400
Задан address, но не задана network. Повтор: Нет — укажите сеть.
​
400
percent вне диапазона 0–100. Повтор: Нет.
​
400
Сумма долей всех правил превысила 100 %. Повтор: Нет — уменьшите доли или удалите правило.
​
400
merchant_id не является корректным UUID. Повтор: Нет.
​
400
Получатель сплита — вы сами. Повтор: Нет — укажите другого получателя.
​
400
refund_hold_hours вне диапазона 0–2160 (90 суток). Повтор: Нет.
​
400
rule_id не является корректным UUID. Повтор: Нет.
​
404
Правило не найдено. Повтор: Нет.
​
503
Сплит‑платежи недоступны на этом шлюзе. Повтор: Да (backoff).
Методы: /v1/split/rule*, /v1/split/config/*.

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

​
400
Получатель не определён: не передан email и у платежа нет payer_email. Повтор: Нет — передайте email либо задавайте payer_email при создании счёта.
​
503
Почта не настроена на этом шлюзе. Повтор: Да (backoff) — либо шлите письмо сами.
Метод: /v1/payment/send-email.

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

Если у шлюза включён комплаенс‑провайдер, адрес назначения выплаты/возврата проверяется перед отправкой.
​
403
Адрес назначения заблокирован AML‑проверкой. Повтор: Нет — используйте другой адрес.
​
400
Для проверки не передан адрес назначения. Повтор: Нет.
Методы: /v1/payout, /v1/payment/refund, /v1/wallet/blocked-address-refund.

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

​
400
У мерчанта нет привязанного владельца. Повтор: Нет.
​
400
Неизвестная валюта. Повтор: Нет.
​
400
Некорректная сумма. Повтор: Нет.
​
400
Сумма перевода некорректна (≤0 или неверный формат). Повтор: Нет.
​
400
Недостаточно средств на балансе для перевода. Повтор: Да, после пополнения.
Метод: /v1/transfer/to-personal.

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

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

​
400
Неизвестная валюта в наборе. Повтор: Нет — исправьте валюту.
​
400
Не указана сеть для элемента. Повтор: Нет — укажите сеть.

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

​
400
Неизвестная валюта. Повтор: Нет — исправьте валюту.
​
400
discount_percent вне −99…99. Повтор: Нет — задайте значение в диапазоне.

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

​
400
При enabled: true значение accuracy_percent вне 1–5 %. Повтор: Нет — задайте значение 1–5 %.

​
vrcs

​
400
Ошибка чтения состояния VRCS. Повтор: Да (backoff) — повторите позже.

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

​
webhook

​
400
Не передан url / url_callback. Повтор: Нет — передайте URL.
​
400
Некорректный или запрещённый (приватный/локальный) URL. Повтор: Нет — исправьте URL.
​
503
Ваш эндпоинт не принял пробное тело. Повтор: Да (backoff) — после починки эндпоинта.

​
autowithdraw

​
400
Неизвестный актив. Повтор: Нет — исправьте актив.
​
400
Некорректный порог. Повтор: Нет — исправьте порог.
​
400
Не хватает обязательного поля. Повтор: Нет — добавьте поле.
При set адрес также проходит валидацию сети — возможны payout.bad_address и payout.address_network_mismatch (см. раздел payout).

​
apiallow — IP‑allowlist

​
400
Некорректный IP или CIDR. Повтор: Нет — исправьте IP/CIDR.
​
400
Нельзя включить контроль с пустым списком. Повтор: Нет — добавьте хотя бы один адрес.

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

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

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

Формат ответа и коды ошибок

HTTP‑классы и правила обработки.

FAQ и устранение неполадок

что делать при частых ошибках.

Глоссарий

термины, встречающиеся в описаниях.