Ошибки
Все ошибки API имеют один формат и осмысленный HTTP-код. Обрабатывайте код, а не текст сообщения: тексты могут меняться и локализованы на русский.
API v1 · обновлено 2026-09-12
Формат ответа
| Поле | Описание |
|---|---|
error.code | Машиночитаемый код в snake_case. Стабилен — используйте его в логике. |
error.message | Человекочитаемое описание для логов и разработчика. Не показывайте покупателю как есть. |
error.param | Необязательно: имя поля запроса, к которому относится ошибка (amount, customer.email). |
error.details | Необязательно: массив с подробностями валидации. |
Успешные ответы не содержат поля error. Проверять достаточно HTTP-статус: 2xx — успех, всё остальное — объект ошибки.
Коды
| HTTP | code | Когда | Что делать |
|---|---|---|---|
| 400 | validation | Тело не является корректным JSON, неверный тип или формат поля, недопустимое значение enum. В ответе есть param — имя поля. | Исправьте запрос. Не повторяйте без изменений. |
| 401 | unauthorized | Нет заголовка Authorization / X-Public-Id, ключ не найден или отозван. | Проверьте ключ и режим (sk_live_ / sk_test_). См. Аутентификация. |
| 401 | signature_invalid | X-Signature (или Signature) не совпала с HMAC-SHA256 от полученного тела. | Подписывайте ровно ту строку, которую отправляете; не пересериализуйте JSON. |
| 403 | project_not_active | Проект не прошёл модерацию, отклонён или заблокирован; боевой ключ не может создавать счета. | Проверьте статус проекта в кабинете; до одобрения используйте sk_test_. |
| 404 | invoice_not_found | Счёт (или возврат) с таким id не существует в этом проекте либо создан ключом другого режима. | Проверьте идентификатор и режим ключа. |
| 409 | order_id_conflict | orderId уже занят счётом с другими параметрами (суммой, методом, feePayer). | Используйте новый orderId или получите существующий счёт через GET /invoices?orderId=. |
| 422 | amount_out_of_range | Сумма меньше минимума или больше максимума для метода / проекта. | Сверьтесь с GET /methods (min, max). |
| 422 | method_unavailable | Указанный method отключён для проекта или временно недоступен. | Создайте счёт без method или выберите другой из GET /methods с enabled: true. |
| 422 | refund_exceeds_amount | Сумма возврата больше невозвращённого остатка по счёту. | Запросите GET /invoices/{id} и уменьшите сумму. |
| 422 | insufficient_balance | На балансе мерчанта не хватает средств для возврата. | Дождитесь новых оплат или сделайте частичный возврат. |
| 429 | rate_limited | Больше 60 запросов в секунду на ключ или опрос одного счёта чаще 1 раза в 3 секунды. | Повторите через Retry-After секунд. Для статусов используйте вебхуки. |
| 500 | internal | Ошибка на нашей стороне. | Повторите через несколько секунд; POST /invoices безопасно повторять благодаря orderId. Повторяется — напишите в поддержку, указав время и orderId. |
| 503 | provider_unavailable | Способ оплаты временно недоступен на стороне банков или идут технические работы. | Повторите позже или создайте счёт без method. Состояние — на странице статуса. |
Какие ошибки повторять
- Повторять:
429(черезRetry-After),500,503и сетевые таймауты — с задержкой, растущей от 250 мс, не более 4–5 раз. - Не повторять без изменений:
400,401,403,404,409,422— они детерминированы. POST /invoicesс тем жеorderIdбезопасно повторять всегда: дубль не создастся.
Ошибки при доставке вебхуков
Это отдельный механизм: если ваш сервер ответил не 2xx, мы повторим вебхук по расписанию, а код и тело вашего ответа сохраним в истории доставок. Подробнее — Вебхуки → Повторы.