Если в процессе обработки запроса произойдёт ошибка, API вернёт объект ошибки и соответствующий HTTP-код. Ориентируйтесь на машиночитаемое поле code.

​
Формат ошибки

Все прикладные ошибки возвращаются в едином конверте: 
{
  "error": {
    "code": "payment_not_found",
    "message": "Payment not found",
    "request_id": "01jbx9q8h7m2k3n4p5r6s7t8v9"
  }
}
​
code
string
Машиночитаемый код ошибки.
​
message
string
Человекочитаемое описание.
​
details
object
Структурированный контекст ошибки. Возвращается только у ошибок валидации (содержит fields); в остальных ответах поле отсутствует.
​
request_id
string
Идентификатор запроса для трассировки.

​
Справочник кодов

КодHTTPКогда возникает
invalid_request400Некорректные параметры запроса.
unauthorized401Невалиден заголовок Authorization.
merchant_inactive403API-ключ принадлежит неактивному проекту.
payment_not_found404Платёж не найден или принадлежит другому проекту.
refund_not_found404Возврат не найден или принадлежит другому проекту.
refund_not_allowed409Возвраты отключены, неподходящий статус платежа или уже есть незавершённый возврат.
refund_amount_exceeds409Сумма возврата больше доступного остатка.
insufficient_balance409Недостаточно баланса проекта для возврата.
idempotency_key_reused409Тот же Idempotency-Key использован с другим телом запроса.
idempotency_in_progress409Запрос с этим Idempotency-Key ещё обрабатывается.
unroutable_payment422Не нашлось маршрута под данный платеж.
internal_error500Необработанная ошибка на стороне сервера.
service_unavailable503Сервис или его зависимость временно недоступны.
payment_creation_failed503Банк-эквайер отклонил создание платежа.