Стабильный код причины
Постоянный код ошибки используется в логике клиента, отчетах и автоматическом распределении обращений.
Документация / Ошибки API
Обработка ошибок API
Единая схема ответов, кодов ошибок, временных сбоев, неизвестных результатов, диагностики и безопасного восстановления для iGaming-интеграций.
HTTP
результат запроса
Коды
понятная причина
Повтор
безопасное действие
Поиск
диагностика запроса
Цикл обработки ошибки
От ответа API до восстановления
01
Определить тип результата
Проверить HTTP-статус, код причины, категорию ошибки и состояние операции.
02
Сохранить данные для разбора
Записать идентификаторы запроса и операции, адрес метода, время, ссылку провайдера и безопасные параметры.
03
Выбрать безопасное действие
Исправить данные, остановить операцию, повторить запрос с паузой или проверить текущее состояние.
04
Восстановить и проконтролировать
Исключить дубли, выполнить сверку, уведомить ответственных и закрыть причину сбоя.
Обзор
Ошибка должна объяснять причину и следующее действие
Одного ответа HTTP 400 или 500 недостаточно. Надежный API возвращает стабильный код причины, связывает ответ с идентификатором запроса и позволяет понять, нужно ли исправить данные, остановить операцию, повторить запрос или отдельно проверить ее состояние.
Предсказуемое действие
Категория ошибки показывает, можно ли повторить запрос и какие данные необходимо изменить.
Связь для диагностики
Идентификаторы запроса, операции и провайдера связывают клиентские журналы с внутренними системами и поддержкой.
Структура ошибки
Рекомендуемая структура ответа с ошибкой
Ответ должен быть компактным, стабильным и пригодным для автоматической обработки без раскрытия внутренней реализации и чувствительных данных.
Код ошибки
Стабильный идентификатор причины, который не меняется при редактировании поясняющего сообщения.
Описание
Краткое безопасное пояснение без внутреннего кода, запросов к базе, секретов и лишних деталей.
ID запроса
Уникальный идентификатор для поиска операции в журналах и обращения в поддержку.
Дополнительные данные
Допустимый статус, лимит, текущее состояние или безопасная причина отказа.
Можно повторить
Явный признак временной ошибки, который не отменяет защиту операции от повторного выполнения.
Пауза перед повтором
Рекомендуемая задержка в секундах или HTTP-заголовок для ограничения запросов и временной недоступности.
Ошибки полей
Список проблемных полей с кодом причины, путем к значению и безопасным пояснением.
Ссылка на документацию
Постоянная ссылка или идентификатор раздела с описанием причины и способом исправления.
Категории ошибок
Основные категории ошибок
HTTP-статус показывает общий класс результата, а внутренний код уточняет конкретную причину и допустимое действие.
Ошибка входных данных
Неверный формат, отсутствующее обязательное поле, неподдерживаемое значение, точность суммы или нарушенная структура запроса.
Ошибка аутентификации
Отсутствующий, просроченный или неверный токен, ключ API, подпись, время запроса или одноразовый идентификатор.
Недостаточно прав
Клиент распознан, но не имеет нужной роли, бренда, рынка или разрешения на действие.
Объект не найден
Игрок, платеж, раунд, проверка KYC, провайдер или другой объект не существует либо недоступен клиенту.
Конфликт состояния
Версия или состояние объекта изменились либо идентификатор операции уже использован с другими параметрами.
Нарушение бизнес-правила
Недостаточный баланс, превышенный лимит, заблокированный игрок, запрещенный рынок или недопустимый переход статуса.
Слишком много запросов
Превышено допустимое число запросов для клиента, метода, роли или критической операции.
Провайдер недоступен
Внешний сервис недоступен, отвечает с задержкой или временно не принимает операции.
Внутренняя ошибка
Неожиданная ошибка платформы без раскрытия внутренних деталей, но с идентификатором для диагностики.
Повтор и восстановление
Повтор запроса и неизвестный результат
Повтор безопасен только после определения типа ошибки и проверки, могла ли исходная операция уже выполниться.
01
Проверить, разрешен ли повтор
Ошибки данных, прав и бизнес-правил обычно требуют исправления запроса, а не повторной отправки.
02
Сохранить тот же ключ операции
Повтор финансовой, игровой или другой критической операции не должен создавать новый результат.
03
Увеличивать паузу между попытками
Интервалы постепенно увеличиваются, учитывают указанное сервером время и ограничивают общее число попыток.
04
Остановиться и передать на проверку
После исчерпания попыток операция фиксируется как незавершенная и передается на ручную проверку или сверку.
Отсутствие ответа не означает отказ операции
При разрыве соединения после отправки запроса результат может остаться неизвестным. Перед повтором необходимо проверить состояние по идентификатору операции или дождаться доверенного уведомления.
Диагностика и контроль
Журналы, идентификаторы, показатели и уведомления
Диагностика должна восстанавливать путь запроса между платформой, адаптером и внешним провайдером без хранения лишних чувствительных данных.
Контекст для разбора
Идентификаторы запроса, связи, операции и внешнего провайдера.
Адрес метода, способ HTTP-запроса, окружение, клиент, время и длительность ответа.
HTTP-статус, код ошибки, число попыток и финальное состояние.
Скрытые чувствительные поля, безопасные заголовки и результат проверки подписи.
Контроль и уведомления
Доля ошибок по методу, провайдеру, клиенту и категории причины.
Рост долгих ответов, HTTP 5xx, неверных подписей и ограничений частоты.
Количество повторов, операций с неизвестным результатом и задач на восстановление.
Уведомления с порогами, ответственными и правилами передачи проблемы.
Тестирование
Что проверить в тестовой среде
Тестовая среда должна воспроизводить каждую важную категорию ошибки и подтверждать правильное поведение клиента, повторных попыток и контроля.
Ошибки входных данных
Пропущенные поля, неверные типы, неподдерживаемые значения, точность суммы и несколько ошибок одновременно.
Доступ и права
Неверный ключ, просроченный токен, ошибочная подпись, чужая роль, запрещенный IP и повторный одноразовый идентификатор.
Нет ответа и неизвестный результат
Разрыв соединения до отправки, после приема операции и во время получения финального ответа.
Ограничение частоты
HTTP 429, рекомендованная пауза, параллельные запросы и восстановление после окончания ограничения.
Ошибки провайдера
Недоступность, обслуживание, некорректный ответ, задержанное уведомление и противоречивый статус.
Повтор и защитная остановка
Ограничение числа попыток, увеличение пауз, временная остановка запросов, контролируемое восстановление и ручная передача проблемы.
Чек-лист перед запуском
Рабочая интеграция запускается после проверки структуры ошибок, поведения клиента, защиты от дублей и диагностики.
Все ошибки возвращают стабильный код причины и идентификатор запроса.
Подробности ошибок не раскрывают секреты и внутреннюю реализацию.
Временные и постоянные категории ошибок описаны в документации.
Повтор критической операции использует тот же ключ защиты от дублей.
Неизвестный результат обрабатывается через проверку состояния или доверенное уведомление.
Настроены журналы, показатели, уведомления, очередь восстановления и правила передачи проблемы.
Нужно привести ошибки API к единому формату?
Передайте текущие HTTP-ответы, коды ошибок, правила повторов и проблемные сценарии. APIACE поможет определить единую модель ошибок, безопасное восстановление и контроль.