Коды ошибок

Любой ответ с ошибкой имеет одинаковую структуру:

{
  "result": null,
  "error": {
    "code": "insufficient_funds",
    "message": "There are insufficient funds on the card."
  }
}

• error.code — стабильный машиночитаемый идентификатор в нижнем регистре. Проверяйте именно его в коде.
• error.message — человекочитаемое описание (на английском). Только для отображения, не парсите его.
• Некоторые ошибки содержат необязательный объект error.data с дополнительным контекстом (например, имя поля или метку blocked_until).

Важное изменение

Шлюз больше не возвращает сырые коды или текст процессинга (числовые коды UzCard/Humo/Paynet или сообщения провайдера). Одинаковая ситуация от разных провайдеров теперь приводится к единому error.code с понятным сообщением. Если раньше ваша интеграция проверяла processing_error плюс сырой код/текст в message/data, перейдите на проверку конкретного error.code ниже.

Ошибки карты

Код	Сообщение	Когда возникает
card_not_found	The card was not found.	Карта (id/токен) не существует или не принадлежит мерчанту.
card_expired	The card has expired.	Истёк срок действия карты (отказ провайдера).
card_is_blocked	The card is blocked.	Карта заблокирована эмитентом.
card_is_blocked_in_processing_center	The card is temporarily blocked. Please try again later.	Процессинг временно заблокировал карту.
card_temporarily_blocked	The card is temporarily blocked. Please try again later.	Блокировка анти-фродом. data.blocked_until, data.reason.
card_not_active	The card is not active.	Карта неактивна в процессинге или отключён SMS. data: is_active, status_message, sms_info.
card_is_not_supported	This card is not supported.	Тип/вендор карты не поддерживается.
card_is_already_activated	The card is already active.	Попытка повторной активации уже активной карты.
card_exists	The card is already added.	Карта уже добавлена для этого пользователя.
invalid_card	The card is invalid.	Некорректные данные карты.
invalid_card_token	The card token is invalid.	Некорректный токен карты.
pan_not_valid	The card number is invalid.	PAN не прошёл валидацию.
lost_card	The card has been reported lost.	Отказ провайдера: карта заявлена как утерянная.
stolen_card	The card has been reported stolen.	Отказ провайдера: карта заявлена как украденная.
card_captured	The card cannot be used. Please contact your bank.	Отказ провайдера: изъять карту.
restricted_card	Operations on this card are restricted.	Отказ провайдера: карта ограничена.

Средства, лимиты и сумма

Код	Сообщение	Когда возникает
insufficient_funds	There are insufficient funds on the card.	Недостаточно средств на карте.
insufficient_deposit	There is not enough deposit to complete the operation.	Недостаточно депозита мерчанта/терминала (A2C, service payment).
invalid_amount	The amount is invalid.	Сумма вне допустимого диапазона или некорректна.
limit_exceeded	The card limit has been exceeded.	Превышен лимит карты/терминала (отказ провайдера).
daily_limit_used_for_this_card	The daily limit for this card has been reached.	Достигнут дневной лимит карты.

Отказ / обработка транзакции

Код	Сообщение	Когда возникает
do_not_honor	The transaction was declined by the card issuer.	Общий отказ эмитента (do not honor).
call_issuer	The transaction was declined. Please contact your bank.	Эмитент просит связаться с банком.
transaction_not_permitted	This transaction is not permitted for the card.	Операция не разрешена для этой карты.
duplicate_transaction	A duplicate transaction was detected.	Провайдер обнаружил дубликат.
issuer_unavailable	The card issuer is temporarily unavailable. Please try again later.	Эмитент/хост временно недоступен.
invalid_merchant	The merchant configuration is invalid.	Проблема конфигурации мерчанта/терминала.
processing_error	The payment could not be processed. Please try again.	Общий сбой обработки без конкретного кода.
transaction_not_found	The transaction was not found.	Нет транзакции с указанным id/externalId.
transaction_not_available_for_payment	transaction_not_available_for_payment	Транзакция не в состоянии оплаты.
transaction_not_available_for_cancel	transaction_not_available_for_cancel	Транзакцию нельзя отменить.
error_at_pay	error_at_pay	Сбой подтверждения оплаты (общая обёртка).

Код подтверждения (OTP) и PIN

Код	Сообщение	Когда возникает
invalid_otp	The confirmation code is incorrect.	Неверный код OTP.
otp_expired	The confirmation code has expired.	Истёк срок действия OTP.
try_new_otp	Please request a new confirmation code.	Проверка OTP не удалась; запросите новый.
otp_code_already_sent	A confirmation code has already been sent. Please wait before requesting a new one.	OTP уже был отправлен недавно.
incorrect_pin	The PIN is incorrect.	Неверный PIN (отказ провайдера).
pin_attempts_exceeded	The number of PIN attempts has been exceeded.	Слишком много неверных попыток PIN.
too_many_attempts	Too many attempts. Please try again later.	Сработала защита по числу попыток.

Телефон карты / SMS

Код	Сообщение	Когда возникает
sms_not_active	SMS notification is not active for this card.	У карты нет активной SMS/OTP функции.
phone_not_match	The phone number does not match the card.	Переданный телефон не совпадает с телефоном карты.
card_phone_not_linked	No phone number is linked to this card.	К карте не привязан телефон.
card_has_no_phone	No phone number is registered for this card.	У карты нет зарегистрированного телефона.

MyID / PINFL (проверка личности)

Применяется, когда у мерчанта включены is_myid_required и/или is_pinfl_required (например, A2C).

Код	HTTP	Когда возникает
official_profile_required	403	Требуется MyID, но у пользователя нет официального профиля. Создайте через /userCard/createOfficialProfile/.
merchant_user_myid_not_verified	400	Пользователь мерчанта не существует / MyID не проверен.
pinfl_check_required	403	Требуется PINFL, но он не проверен для этой карты.
pinfl_not_match	403	Проверенный PINFL не совпадает с официальным профилем / картой.

Оплата услуг (Paynet / HGT / uzsuv / Hamkorbank / …)

Числовые коды и текст провайдера не возвращаются — они унифицированы ниже.

Код	Сообщение	Когда возникает
service_payment_error	The payment could not be completed. Please try again.	Общий сбой оплаты услуги.
account_not_found	The account was not found.	Абонент / счёт не найден у провайдера.
provider_unavailable	The service provider is temporarily unavailable. Please try again later.	Провайдер недоступен / перегружен / отказал.
service_under_maintenance	The service is under maintenance. Please try again later.	Профилактика у провайдера.
payment_cancel_not_allowed	This payment cannot be cancelled.	Отмена недоступна / истёк срок у провайдера.
service_not_found	The service was not found.	Услуга/товар не найдены.
service_not_available	The service is temporarily unavailable. Please try again later.	Услуга временно недоступна.
service_temporarily_not_accepting_payments	service_temporarily_not_accepting_payments	Услуга сейчас не принимает платежи.
pinfl_check_required	см. выше	Некоторые услуги требуют проверенный PINFL перед оплатой.

OFD / фискализация

Код	Сообщение	Когда возникает
ofd_commitent_or_subcommission_not_active	ofd_commitent_or_subcommission_not_active	У комитента (TIN) или субкомиссии (PINFL) позиции чека нет активного договора в каталоге OFD. data: itemIndex, tin, pinfl.
ofd_check_already_generated	ofd_check_already_generated	Фискальный чек уже сформирован для этой транзакции.
ofd_too_many_requests_for_this_receipt	ofd_too_many_requests_for_this_receipt	Слишком много запросов чека для этой транзакции.
ofd_check_not_found	ofd_check_not_found	Фискальный чек не найден.

Авторизация, валидация и общие

Код	HTTP	Когда возникает
permission_denied	401 / 400	Отсутствуют/неверны учётные данные, либо у мерчанта нет доступа к API (A2C, A2C-by-PAN, split, фискализация).
ip_not_allowed	403	IP вызывающего не в белом списке мерчанта/ключа.
validation_error	400	Некорректное тело/параметры запроса. data может содержать детали по полям.
field_required	400	Отсутствует обязательное поле. data.field.
field_not_valid	400	Некорректное значение поля. data.field.
not_found	404	Запрошенный ресурс не найден.
bank_not_found	400	Банк не найден.
terminal_does_not_exist	400	Нет доступного терминала для операции.
hold_not_found	400	Hold не найден.
gateway_not_working	400	Мерчант неактивен / не настроен для этого шлюза.
rate_limit_exceeded	429	Слишком много запросов.
payload_too_large	413	Тело запроса превышает лимит (64 КБ).
server_error	500	Непредвиденная ошибка сервера.
unknown_error	400	Произошла непредвиденная ошибка. Повторите попытку.

INFO

Список охватывает наиболее частые коды. Со временем могут появляться новые, поэтому всегда корректно обрабатывайте неизвестный error.code (как общий сбой).