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

WinWallet Merchant API использует стандартные HTTP-коды и единую структуру ошибок ErrorSchema в теле ответа для бизнес-методов.

Структура ErrorSchema

Поле	Тип	Описание
`message`	string	Человекочитаемое описание ошибки
`error_code`	integer	Код ошибки (часто совпадает с HTTP-статусом)

Обёртка ответа при result: false:

{
  "result": false,
  "data": null,
  "error": {
    "message": "Описание ошибки",
    "error_code": 401
  }
}
        

HTTP-статусы и коды

HTTP	error_code	Когда возникает	Рекомендация
200	—	Успех; `result: true`	Обработать `data`
401	401	Нет или неверен Bearer token, неверный `X-Merchant`	Проверить учётные данные, не повторять запрос без исправления
404	404	Инвойс не найден	Проверить `invoice_id` и окружение (sandbox/production)
409	409	Дубликат `merchant_transaction_id`	Использовать новый ID или вернуть существующий инвойс из вашей БД
422	—	Ошибка валидации полей (формат `HTTPValidationError`)	Исправить тело запроса по `detail[].loc` и `msg`
500	500	Внутренняя ошибка сервера	Повтор с backoff; эскалация в поддержку при повторении

Ошибки валидации (422)

Ответ не использует result/error, а массив detail:

        {
          "detail": [
            {
              "loc": ["body", "callback_url"],
              "msg": "Input should be a valid URL",
              "type": "url_parsing"
            }
          ]
        }
        

Типичные причины: неверный формат URL, сумма ≤ 0, пустой description, отсутствие обязательных полей, неверный currency.

Стратегия обработки на стороне мерчанта

Логируйте error_code, message и correlation ID запроса.
Не считайте оплату завершённой только по HTTP 200 при создании — ждите статус PAID или webhook.
Для 409 храните идемпотентность по merchant_transaction_id на своей стороне.
Для 500 и сетевых таймаутов используйте ограниченное число повторов с jitter.

01 июня 2026