Ошибки

Отказ банка — это успешный HTTP-ответ с failureCode внутри. Ошибка запроса — это HTTP-код.

Два разных вида ошибок

Ошибка запроса — вы отправили что-то не то или сейчас нельзя: приходит HTTP-код 4xx или 5xx и объект error всегда одной формы: type — род ошибки, code — машинный код, message — объяснение для человека, param — поле, если ошибка относится к конкретному, и request_id.

Ветвитесь по type и code, а не по тексту message: текст мы можем уточнить в любой момент, коды — нет.

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "Idempotency-Key уже использован с другим телом запроса",
    "request_id": "req_4f2c8a1b9d3e"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "pan должен состоять из 16 цифр",
    "param": "pan",
    "request_id": "req_4f2c8a1b9d3e"
  }
}

Отказ по платежу — запрос корректен, но банк не провёл операцию. HTTP-ответ успешный, статус платежа FAILED, причина в failureCode. Не обрабатывайте это как сбой интеграции.

{
  "id": "cmsr9x8y",
  "status": "FAILED",
  "failureCode": "DECLINED"
}

Идентификатор запроса

Каждый ответ содержит заголовок Request-Id, а в ошибках он ещё и в теле — error.request_id. Сохраняйте его в своих журналах.

Когда что-то пойдёт не так, назовите нам этот идентификатор — мы найдём ваш запрос за секунду. Без него разбор начинается с вопроса «когда примерно это было», и на него редко есть точный ответ.

Если вы пришлёте свой Request-Id, мы используем его вместо своего — так сквозная трассировка не рвётся на нашей границе.

HTTP-коды

Причины отказов

Что показать клиенту и стоит ли повторять:

Дальше по теме