Обработка ошибок

Для обработки ошибок проверяйте HTTP-статус, поле status и машинный код code. Текст message предназначен для пояснения: он может уточняться или переводиться, поэтому не используйте его как условие в коде.

Формат ответа

Передавайте заголовок Accept: application/json, чтобы получать ошибки в JSON. При явном предпочтении text/html сервис может вернуть HTML-страницу ошибки.

{
  "status": "error",
  "code": "DUPLICATE_ORDER_ERROR",
  "message": "Order already exists"
}

Пример отсутствующего обязательного поля, HTTP 400:

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "Field required",
  "field_errors": {
    "merchant_id": ["Field required"]
  }
}

HTTP-статус и результат операции

HTTP-статус и код ошибки не заменяют статус Invoice, Refund или Withdrawal. При неопределённом результате проверяйте существующую операцию через соответствующий метод статуса или webhook. Не создавайте новую операцию с новым order, пока не выяснен результат предыдущей. При ошибке дублирования сначала найдите уже созданную операцию.

Единый каталог ошибок

Ниже — 63 кода общего каталога. Описания взяты из кода сервиса; фактический message может содержать уточнение. Все записи текущего каталога имеют базовый HTTP-статус 400, но фактический HTTP-ответ зависит от метода и обработчика, как описано выше. Доступные коды зависят от подключения; не каждый код встречается у каждого метода.

В сообщениях MID означает мерчанта, WL — список разрешённых IP-адресов, BIN — первые цифры карты, определяющие банк-эмитент.

Общие ошибки

Ошибки карт

Другие ошибки платежей и выплат

Ошибки с неопределённым результатом

В каталоге как неокончательные отмечены PAYMENT_SYSTEM_ERROR, PROVIDER_ERROR, COMMON_ERROR, PAYMENT_DETAILS_UNAVAILABLE, SERVICE_UNAVAILABLE, INTEGRATION_ERROR, PROCESSING_ERROR, PROCESSING_TIMEOUT, INVALID_TRANSACTION_STATE, TRANSACTION_RESULT_UNKNOWN, UNKNOWN_ERROR и THREEDS_ERROR.

Для них сначала уточните статус существующей операции. Такая ошибка не является разрешением автоматически повторить платёж или выплату. Признак is_final — характеристика каталога, он не передаётся в JSON ошибки. Остальные коды также не заменяют платёжный статус операции.

Дополнительные коды API

В отдельных методах также встречаются коды ниже. Обычно они возвращаются с HTTP 400. Для DUPLICATE_ORDER действия с двухэтапной выплатой могут вернуть HTTP 200 с status: "error".

Если получен незнакомый код, сохраните идентификатор операции, HTTP-статус и ответ API для диагностики. Не считайте неизвестную ошибку успешным выполнением операции; при неопределённом результате уточните её статус.