Ошибки и лимиты

Формат ошибок, полный список кодов и ограничения, о которые можно споткнуться на бою.

Формат

HTTP/1.1 402 Payment Required
X-Request-Id: req_ab12cd34ef56

{
  "error": {
    "code": "insufficient_balance",
    "message": "недостаточно средств на балансе",
    "request_id": "req_ab12cd34ef56",
    "required_usdt": "17.330692",
    "balance_usdt": "4.020000"
  }
}

Ориентируйтесь на code, а не на текст message — тексты мы можем менять. request_id есть в каждом ответе, включая успешные; приложите его к обращению в поддержку, и мы сразу найдём запрос в логах.

Отклонённый платёж — это не ошибка запроса Если платёж создан, но не прошёл, вы получите 200 и объект платежа со статусом failed, а причина будет в поле error. Коды ниже относятся к запросам, которые мы не приняли вовсе.

Коды

HTTP	Код	Что делать
400	`invalid_request`	Поправить тело запроса
400	`missing_idempotency_key`	Добавить заголовок `Idempotency-Key`
400	`invalid_qr`	Ссылка не похожа на QR СБП или просрочена
400	`unsupported_qr`	QR подписки/привязки — оплатить нельзя
400	`unsupported_variable_amount`	QR без фиксированной суммы
400	`amount_mismatch`	Ваша сумма не совпала с суммой в QR — проверьте, тот ли это QR
400	`amount_limit_exceeded`	Сумма выше лимита на один платёж
401	`unauthorized`	Ключ неверен, отозван или не передан
402	`insufficient_balance`	Пополнить баланс
403	`partner_suspended`	Доступ приостановлен — написать в поддержку
403	`ip_not_allowed`	Адрес не в вашем списке разрешённых
403	`recipient_blocked`	Оплата этому получателю запрещена
403	`daily_limit_exceeded`	Исчерпан суточный лимит
404	`not_found`	Платёж не найден или принадлежит другому аккаунту
409	`idempotency_conflict`	Тот же ключ с другим телом — взять новый ключ
409	`duplicate_qr_in_flight`	По этому QR уже идёт платёж — дождаться его исхода
409	`qr_changed`	Данные QR изменились с момента проверки — получить QR заново
422	`qr_unresolvable`	Не удалось получить реквизиты — повторить позже
429	`rate_limited`	Снизить темп, см. `Retry-After`
503	`rate_unavailable`	Курс устарел, платежи временно закрыты — повторить через минуту
503	`gateway_unavailable`	Шлюз недоступен — повторить позже
503	`gateway_busy`	Слишком много одновременных платежей — повторить
503	`maintenance`	Плановая пауза
500	`internal_error`	Сообщить нам `request_id`

Как повторять запросы

Ошибки 429 и 503 — временные, их можно повторять с задержкой (разумно начать с 2 секунд и удваивать). Повторяйте с тем же Idempotency-Key — иначе рискуете оплатить один QR дважды.

Ошибки 4xx, кроме 429, повторять бессмысленно: запрос надо исправить.

Обрыв связи — не повод создавать новый платёж Если соединение оборвалось и вы не знаете исход, повторите тот же запрос с тем же ключом идемпотентности или запросите GET /v1/payments/{id}. Новый ключ создаст второй платёж по тому же QR.

Лимиты

Ограничение	Значение по умолчанию
Минимальная сумма платежа	10 ₽
Максимальная сумма платежа	100 000 ₽
Оборот в сутки	не ограничен
Создание платежей	3 запроса в секунду, всплеск до 10
Остальные запросы	20 запросов в секунду
Одновременных платежей	2
Время ответа `POST /v1/payments`	до 90 секунд

Лимиты сумм повышаются индивидуально — напишите в поддержку, когда объёмы вырастут.

Безопасность ключа

Ключ даёт право тратить ваш баланс — держите на балансе рабочий остаток, а не резерв.
Ключ можно заменить в боте: новый начинает работать сразу, старый перестаёт через 24 часа, так что интеграция переключается без простоя. Кнопка «Отозвать все» гасит все ключи мгновенно.
По желанию можно ограничить доступ списком IP-адресов — скажите нам, с каких адресов ходит ваш сервер.