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

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

Частые вопросы — короткие ответы. Нужна **пошаговая диагностика** по симптому (деревья «платёж
застрял», «вебхук не приходит», таймауты) — на странице
[Что делать, если не работает](/guides/troubleshooting).

Полный список кодов ошибок — [Справочник кодов ошибок](/reference/errors-catalog).

***

## Аутентификация и подпись

<AccordionGroup>
  <Accordion title="Почему я получаю 401 на каждый запрос?">
    Почти всегда причина одна: **подписали одну строку тела, а отправили другую**. Библиотека могла
    переупорядочить поля JSON или добавить пробелы, и байты тела перестали совпадать с подписанными.

    **Что проверить:**

    1. Сериализуйте тело **один раз** в переменную и используйте её и для подписи, и для отправки.
    2. Каноническая строка — ровно `timestamp\nPOST\npath\nbody`, с переводами строк `\n`.
    3. `path` — с ведущим слэшем (`/v1/payment`), без базового URL.
    4. Подпись — hex в нижнем регистре.

    → [Как подписать запрос](/guides/signing-requests)
  </Accordion>

  <Accordion title="401 auth.bad_timestamp — что это?">
    `X-Timestamp` **отсутствует или не число**. Передавайте unix‑секунды (целое), не миллисекунды.

    <Note>
      Если часы разошлись больше чем на 5 минут — код будет **`merchant.bad_signature`** (проверка окна
      ±5 мин встроена в сверку подписи), а не `auth.bad_timestamp`. Синхронизируйте время (NTP).
    </Note>
  </Accordion>

  <Accordion title="401 auth.ip_not_allowed, хотя подпись верна">
    У вас включён [IP‑allowlist](/reference/api-allowlist), а запрос идёт с адреса вне списка. Либо
    добавьте IP вашего backend, либо временно выключите контроль.
  </Accordion>

  <Accordion title="Подпись запроса работает, а вебхук «не проходит» проверку">
    Это **разные алгоритмы**. Подпись запроса — `timestamp\nMETHOD\npath\nbody`. Подпись вебхука —
    `timestamp.сырое_тело` (точка‑разделитель, без метода и пути), другим секретом. →
    [Объект вебхука](/reference/webhook-object)
  </Accordion>
</AccordionGroup>

## Платежи

<AccordionGroup>
  <Accordion title="Создал платёж, а address пустой">
    Скорее всего это **валюто‑агностичный счёт** (`is_multi: true`): вы не задали `to_currency`/`network`,
    и адрес выделится только после того, как покупатель выберет валюту на hosted‑странице через
    [`/v1/pay/{id}/select`](/reference/pay-select). Если адрес нужен сразу — задайте валюту и сеть при
    создании. → [Три режима создания счёта](/guides/payment-modes)
  </Accordion>

  <Accordion title="payment.network_required при создании">
    У валюты несколько сетей (например, у `USDT` их много), а `network` вы не указали. Укажите сеть явно
    или используйте валюту с единственной сетью. → [Поддерживаемые сети](/reference/basics-networks)
  </Accordion>

  <Accordion title="payment.below_minimum">
    Сумма ниже минимума сети. На дорогих сетях (Ethereum, Bitcoin) минимум есть. Увеличьте сумму или
    используйте дешёвую сеть (Tron, Polygon, BSC).
  </Accordion>

  <Accordion title="Покупатель оплатил, но статус всё ещё не paid">
    Проверьте промежуточные статусы: `confirm_check` означает, что транзакцию видят и **ждут
    подтверждений** сети. Число подтверждений зависит от суммы и сети — крупный платёж ждёт дольше. Пока
    не достигнут порог, статус не станет `paid`. → [Приём первого платежа](/guides/accept-first-payment)
  </Accordion>

  <Accordion title="Пришло меньше, чем выставил, — что делать?">
    Зависит от настроек. Если сумма в пределах [допуска](/reference/payment-accuracy) — счёт всё
    равно `paid`. Если нет и срок вышел — `wrong_amount`, и средства вернутся при включённом
    [автовозврате](/reference/payment-autorefund). → [Недоплата и переплата](/guides/under-overpayment)
  </Accordion>
</AccordionGroup>

## Вебхуки

<AccordionGroup>
  <Accordion title="Вебхук вообще не приходит">
    Пройдите по списку:

    1. **Endpoint зарегистрирован?** Вызовите [`/v1/webhooks`](/reference/webhooks-register) и
       сохраните секрет. Без регистрации доставок нет вовсе — даже per‑объектный `url_callback`
       игнорируется (без секрета endpoint подписывать нечем, доставка не создаётся).
    2. **URL публично доступен по HTTPS?** Приватные/локальные адреса запрещены SSRF‑проверкой.
    3. **Отправьте пробное событие** и посмотрите `status_code`. → [Отладка вебхуков](/guides/webhooks-debug)
    4. **Проверьте журнал доставок** — статус `pending`/`dead` и `last_error` подскажут причину. →
       [`/v1/webhooks/deliveries`](/reference/webhooks-deliveries)
  </Accordion>

  <Accordion title="Вебхук приходит, но подпись не сходится">
    * Берёте ли вы **сырое тело** (до JSON‑парсинга)? Пересериализация меняет байты.
    * Правильный ли алгоритм: `hex(HMAC-SHA256(secret, "{timestamp}." + сырое_тело))`?
    * Тот ли секрет — из [`/v1/webhooks`](/reference/webhooks-register), а не ключ API?
    * Пробные тела (`is_test: true`) **не подписаны** — их проверять подписью не нужно.
  </Accordion>

  <Accordion title="Один и тот же вебхук приходит несколько раз">
    Это нормально: доставка **at‑least‑once**. Обязательно дедуплицируйте по `uuid` + `status` и
    обрабатывайте повтор как no‑op. → [Настройка вебхуков](/guides/webhooks-setup#обрабатывать-идемпотентно)
  </Accordion>

  <Accordion title="Обработал вебхук, но Oblodai шлёт его снова">
    Вы вернули не‑`2xx` (или запрос упал по таймауту). Диспетчер считает это провалом и повторяет.
    Отвечайте `2xx` **только после** успешной обработки; если обработка не удалась — тогда да, пусть
    повторит.
  </Accordion>
</AccordionGroup>

## Выплаты и баланс

<AccordionGroup>
  <Accordion title="409 payout.insufficient_funds, хотя на балансе деньги есть">
    Возможны **незрелые средства**: депозит на балансе виден, но ещё не набрал подтверждений и невыводим.
    Выводимый остаток может быть меньше показанного в [`/v1/balance`](/reference/balance). Дождитесь
    подтверждений. Отдельный код для этого случая — `409 payout.funds_maturing`.
  </Accordion>

  <Accordion title="409 payout.funds_maturing">
    Средства ещё дозревают (maturity‑холд для reorg‑безопасности). Это временно — повторите позже с
    backoff или выведите уже зрелую часть.
  </Accordion>

  <Accordion title="400 payout.destination_internal">
    Вы указали адрес, принадлежащий самому шлюзу (self‑dealing запрещён). Укажите внешний адрес.
  </Accordion>

  <Accordion title="400 payout.order_id_required">
    Для выплаты `order_id` **обязателен** — это ваш бизнес‑ключ дедупликации. Всегда задавайте уникальный.
    Он дополняет (а не заменяет) HTTP‑заголовок `Idempotency-Key`. →
    [Устойчивый клиент](/guides/resilient-client#главный-принцип)
  </Accordion>

  <Accordion title="Часть массовой выплаты не прошла">
    Это ожидаемо: элементы независимы. Разбирайте результат **поэлементно** — у неуспешных виден признак
    неудачи и причина. В [батче](/guides/batch-operations) это `items[].status` + `items[].error`, в легаси
    `/v1/payout/mass` — `success: false` + `message`. → [Массовые операции](/guides/batch-operations)
  </Accordion>

  <Accordion title="Как выплатить сразу тысячам получателей и не поймать 429?">
    Используйте **батч** [`POST /v1/payout/batch`](/reference/payout-batch): до **5000** выплат
    **одним** подписанным запросом, обработка асинхронная, результат — через `/v1/batch/info`. Цикл из
    отдельных вызовов гарантированно упрётся в лимит частоты. → [Массовые операции](/guides/batch-operations)
  </Accordion>
</AccordionGroup>

## Общее

<AccordionGroup>
  <Accordion title="Что делать при 500 или 503?">
    Это временные ошибки. Повторяйте с **экспоненциальным backoff**. Благодаря идемпотентности повтор
    денег‑движущих операций безопасен (дубля не будет) — при условии, что вы повторяете **тот же** запрос:
    с тем же HTTP‑заголовком `Idempotency-Key` и тем же `order_id`. →
    [Идемпотентность](/reference/basics-idempotency)
  </Accordion>

  <Accordion title="Что такое Idempotency-Key и обязателен ли он?">
    Это HTTP‑заголовок с любым уникальным значением (до 255 символов), который вы генерируете **до первой
    отправки** и не меняете при ретраях. Повтор с тем же ключом вернёт **тот же ответ** и заголовок
    `Idempotent-Replayed: true` вместо создания дубля.

    Формально не обязателен, но настоятельно рекомендуется. Второй, независимый механизм защиты — ваш
    `order_id` (для выплат он **обязателен**). Опасен только случай, когда нет ни того, ни другого: тогда
    повтор создаст дубль. → [Устойчивый клиент](/guides/resilient-client#главный-принцип)
  </Accordion>

  <Accordion title="Пришёл 409 — операция точно провалилась?">
    **Нет.** Не все `409` финальны:

    * `payout.funds_maturing` — средства дозревают, **повторите позже**, выплата пройдёт;
    * `idempotency.in_progress` — ваш прежний запрос ещё выполняется, **подождите и повторите**;
    * `payout.frozen` — временная защита, **повторите позже**;
    * `payout.insufficient_funds` — вот это по‑настоящему «денег нет», повтор не поможет.

    → [Устойчивый клиент](/guides/resilient-client#не-все-409-финальны)
  </Accordion>

  <Accordion title="Получаю ошибки вида «rate limit» / 429">
    Превышена частота запросов. Снизьте темп и повторяйте с backoff. →
    [Ограничение частоты](/reference/basics-ratelimit)
  </Accordion>

  <Accordion title="Как протестировать, если нет песочницы?">
    Песочницы действительно нет. Большую часть логики можно проверить без переводов (подпись, создание
    счёта, тестовые вебхуки), остальное — малыми суммами на дешёвой сети. →
    [Тестирование интеграции](/guides/testing)
  </Accordion>

  <Accordion title="Как сменить (ротировать) ключ?">
    Только в личном кабинете под 2FA — в публичном API ротации нет. Заморозки выплат при ротации нет. →
    [Безопасность в проде](/guides/production-security#3-ротация-ключа)
  </Accordion>

  <Accordion title="Не нашёл ответа">
    Загляните в [Справочник кодов ошибок](/reference/errors-catalog) и [Глоссарий](/reference/glossary).
    Если проблема не про конкретный код, а про поведение — сверьтесь со страницей нужного метода в
    [Справочнике](/reference/overview).

    Если и это не помогло — создайте тикет в поддержку в кабинете
    [my.oblodai.com](https://my.oblodai.com) (раздел **«Поддержка»**). Приложите ваш `public_id`,
    `uuid` платежа/выплаты и строки лога с префиксом `oblodai:` (в SDK включаются переменной
    `OBLODAI_LOG`, в модулях CMS — галочкой **Debug log**); `secret` **не** прикладывайте.
  </Accordion>
</AccordionGroup>

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

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

  <Card title="Глоссарий" href="/reference/glossary" icon="arrow-right" horizontal />

  <Card title="Как подписать запрос" href="/guides/signing-requests" icon="arrow-right" horizontal />

  <Card title="Отладка вебхуков" href="/guides/webhooks-debug" icon="arrow-right" horizontal />

  <Card title="Тестирование интеграции" href="/guides/testing" icon="arrow-right" horizontal />

  <Card title="Что делать, если не работает" href="/guides/troubleshooting" icon="arrow-right" horizontal />
</CardGroup>