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

Ответ на запрос содержит HTTP‑статус, стандартные заголовки и тело в формате JSON. HTTP‑статус отражает класс ошибки, а тело содержит точный машиночитаемый код.

---

​

Тело ответа при успехе

HTTP 200 OK и конверт с state: 0:

{
  "state": 0,
  "result": { "...": "полезные данные операции" }
}

Подробнее — Формат взаимодействия.

---

​

Тело ответа при ошибке

Конверт с объектом error:

{
  "error": {
    "code": "payout.insufficient_funds",
    "message": "insufficient available balance"
  }
}

• code — машиночитаемый код вида <домен>.<причина>. Именно по нему ветвитесь в коде.
• message — человекочитаемое пояснение. Логировать безопасно, но не полагайтесь на точный текст.

Одно исключение — ограничение частоты (429). Оно отдаёт другую форму: {"state":1,"message":"rate limit exceeded"} — без объекта error и без code. Ваш обработчик ошибок должен учитывать оба варианта: сначала проверьте HTTP‑статус (429 → подождать Retry-After и повторить), и только для прочих читайте error.code. Подробнее — Ограничение частоты.

---

​

Классы ошибок (HTTP‑статусы)

Код	Когда возникает	Что делать
400 invalid	Некорректный запрос: битый JSON, отсутствует поле, недопустимое значение.	Исправить запрос. Повтор без изменений не поможет.
401 unauthorized	Проблема аутентификации: неверная подпись, протухшая метка времени, неизвестный/отозванный ключ, IP не в allowlist.	Проверить подпись, часы, ключ, allowlist.
403 forbidden	Аутентификация прошла, но операция запрещена (заморозка, чужой ресурс и т. п.).	Разобраться в причине; повтор не поможет.
404 not_found	Объект не найден (или скрыт как не найденный, чтобы нельзя было пробить существование чужого UUID).	Проверить идентификатор.
409 conflict	Конфликт состояния: повтор с другим содержимым, объект в неподходящем статусе.	Зависит от кода: payout.funds_maturing / idempotency.in_progress / payout.frozen — повторить позже; прочие — проверить состояние через */info.
429 rate limit	Превышена частота запросов. Тело {"state":1,"message":…} + Retry-After: 60.	Подождать Retry-After секунд и повторить. См. лимит частоты.
503 unavailable	Временная недоступность зависимости (например, оракул курсов).	Повторить с экспоненциальным backoff.
500 internal	Внутренняя ошибка. Детали не раскрываются.	Повторить с backoff.

---

​

Примеры кодов

Список не исчерпывающий — точные коды каждого метода смотрите на его странице.

Код	Значение
auth.bad_timestamp	X-Timestamp отсутствует или не число (само окно ±5 минут — код merchant.bad_signature).
auth.ip_not_allowed	IP вне включённого allowlist.
request.bad_json	Тело не парсится как JSON.
payment.network_required	У валюты несколько сетей, а network не задан.
payment.below_minimum	Сумма ниже минимума сети.
payout.insufficient_funds	Недостаточно доступного баланса.
payout.funds_maturing	Средства ещё дозревают (maturity‑холд).
payout.duplicate_reference	Гонка одновременных вставок с одним и тем же reference/order_id. Обычный повтор (ретрай) не ошибка — вернётся уже созданная выплата.
payout.amount_below_fee	Сумма выплаты меньше сетевой комиссии.

---

​

Как обрабатывать ошибки

1. Ветвитесь по error.code, а не по message. Текст может меняться; код — контракт.
2. 4xx — ваша ошибка запроса. Повтор без изменений даст тот же результат (кроме идемпотентных сценариев, где 409 означает «уже обработано»).
3. 5xx и 503 — временные. Повторяйте с экспоненциальным backoff. Благодаря идемпотентности повтор денег‑движущих операций безопасен.
4. 409 — не всегда финал. payout.funds_maturing, idempotency.in_progress, payout.frozen — временные: повторяйте позже с backoff. Прочие 409 не трактуйте вслепую как «уже сделано» — сверьтесь через */info. → Устойчивый клиент

---

​

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

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

все коды одной таблицей.

Формат взаимодействия

Идемпотентность

Аутентификация