> ## 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.

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

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

***

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

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

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

Подробнее — [Формат взаимодействия](/reference/basics-format).

***

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

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

```json theme={null}
{
  "error": {
    "code": "payout.insufficient_funds",
    "message": "insufficient available balance"
  }
}
```

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

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

***

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

| Код                  | Когда возникает                                                                                                     | Что делать                                                                                                                                             |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400` `invalid`      | Некорректный запрос: битый JSON, отсутствует поле, недопустимое значение.                                           | Исправить запрос. Повтор без изменений не поможет.                                                                                                     |
| `401` `unauthorized` | Проблема аутентификации: неверная подпись, протухшая метка времени, неизвестный/отозванный ключ, IP не в allowlist. | Проверить подпись, часы, ключ, [allowlist](/reference/api-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` секунд и повторить. См. [лимит частоты](/reference/basics-ratelimit).                                                          |
| `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. Благодаря
   [идемпотентности](/reference/basics-idempotency) повтор денег‑движущих операций безопасен.
4. **`409` — не всегда финал.** `payout.funds_maturing`, `idempotency.in_progress`, `payout.frozen` —
   временные: повторяйте позже с backoff. Прочие `409` не трактуйте вслепую как «уже сделано» —
   сверьтесь через `*/info`. → [Устойчивый клиент](/guides/resilient-client#не-все-409-финальны)

***

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

<CardGroup cols={2}>
  <Card title="Справочник кодов ошибок" href="/reference/errors-catalog" icon="arrow-right" horizontal>
    все коды одной таблицей.
  </Card>

  <Card title="Формат взаимодействия" href="/reference/basics-format" icon="arrow-right" horizontal />

  <Card title="Идемпотентность" href="/reference/basics-idempotency" icon="arrow-right" horizontal />

  <Card title="Аутентификация" href="/reference/basics-auth" icon="arrow-right" horizontal />
</CardGroup>