Коды ошибок

Новый клиентский API обычно возвращает бизнес-ошибку с HTTP 200:

{
  "code": 0,
  "body": null,
  "error_code": 471,
  "error_message": "Coupon not found",
  "date": 1784970000000,
  "time_ms": 5,
  "path": "/api/partner/coupons/get"
}

Проверяйте:

HTTP-статус → транспортный результат
code        → результат бизнес-операции
error_code  → конкретная причина ошибки

Не используйте error_message как программный идентификатор.

Краткая таблица нового API

«Нет» означает, что сначала нужно изменить запрос, обновить данные или устранить причину ошибки.

Ошибки авторизации

HTTP 401

Для защищенных маршрутов нового API означает:

• JWT отсутствует;
• JWT имеет неверный формат или подпись;
• токен истек;
• токен был отозван.

Действие:

1. выполнить POST /api/partner/login;
2. получить новый body.token;
3. повторить безопасный запрос чтения.

После 401 на создании купона сначала убедитесь, что исходный запрос не был принят.

HTTP 403

Означает, что:

• токен не имеет клиентской роли;
• используется административный JWT;
• доступ аккаунта запрещен.

Повторный вход с теми же неправильными учетными данными или типом токена проблему не исправит. Проверьте аккаунт и при необходимости обратитесь к менеджеру.

Бизнес-ошибки POST /api/partner/login

Все перечисленные ответы приходят с HTTP 200 и code = 0:

Неизвестный логин и неверный пароль намеренно не различаются и возвращают одинаковую ошибку 1003.

В старом API код 1003 используется в другом контексте — для неверного JWT защищенного маршрута. Старый login любой отказ преобразует в код 99. Всегда учитывайте маршрут.

Ошибки запроса

10 — отсутствуют обязательные данные

Возможные примеры:

• не передано JSON-тело создания купона;
• не передан код в /api/partner/coupons/get.

Для нового POST /api/partner/login отсутствие логина или пароля относится к отдельной бизнес-ошибке 1002.

Проверьте обязательные поля конкретного endpoint.

11 — неверный указатель

Хотя бы один элемент list_bets не соответствует формату:

line_type#game_id#group_id#type_id#rate#coefficient[#player_id]

Действие:

• не считать купон принятым;
• не выполнять окончательное списание;
• получить актуальный готовый указатель из линии;
• не пытаться исправлять указатель по названиям исхода.

12 — неверная сумма

amount отсутствует, имеет несовместимый тип или не является положительным числом.

Проверьте сумму до отправки:

amount > 0

1002 — неверный набор параметров

Используется, в частности, для /api/partner/coupons/results:

• одновременно переданы coupon_ids и даты;
• передана только одна граница периода;
• период неположительный;
• период превышает 24 часа;
• режим запроса невозможно определить.

Исправьте параметры. Повтор неизмененного запроса даст ту же ошибку.

Ошибки проверки исхода

Новый /api/partner/coupons/place возвращает проблемные ставки в:

body.changes[]

Общий формат

{
  "code": 0,
  "body": {
    "changes": [
      {
        "game_id": 737779544,
        "bet_coefficient": 2.19,
        "actual_coefficient": 2.09,
        "change_type": 2,
        "status": "rejected"
      }
    ]
  },
  "error_code": 501,
  "error_message": "Coefficient is change"
}

501 — коэффициент изменился

status = rejected
change_type = 1 или 2

Действие:

• не считать купон принятым;
• показать пользователю актуальный коэффициент;
• получить подтверждение, если это требуется правилами партнера;
• либо использовать заранее согласованный mode = accept.

502 — исход отсутствует

status = no_data
change_type = null

Исход больше не найден в текущей линии. Удалите или обновите его в корзине.

503 — исход заблокирован

status = block
change_type = null

Прием временно недоступен. Не сохраняйте купон как принятый.

504 — ошибка проверки

status = error
change_type = null

Проверка конкретного исхода не была успешно завершена. Не считайте это подтверждением ставки. Обновите линию и предложите повторить операцию позже.

Важно. Бизнес-коды 502, 503 и 504 внутри JSON не равны HTTP-статусам 502, 503 и 504. Всегда различайте error_code и HTTP-код.

506 — ставки одного матча

В одном экспрессе передано несколько исходов одного матча, включая основное событие и связанные саб-события.

Например:

• матч и угловые;
• угловые и фолы;
• разные периоды одного матча.

Оставьте только один исход от дерева матча либо создайте отдельные ординары через multi = true.

507 — недостаточный баланс

{
  "code": 0,
  "error_code": 507,
  "error_message": "Insufficient balance",
  "date": 1753000000000,
  "time_ms": 5,
  "path": "/api/partner/coupons/place"
}

Общей суммы на балансе клиентского аккаунта недостаточно для создания купона или всех ординаров при multi = true.

Операция атомарна:

• ни один купон не создается;
• клиентский баланс не изменяется;
• частичный успех при multi = true невозможен.

Повторяйте запрос только после пополнения клиентского баланса или осознанного уменьшения общей суммы. Положительный баланс может позволить выполнить login, но оказаться недостаточным для конкретного создания: login тогда успешен, а создание возвращает 507.

Ошибки чтения купона

471 — купон не найден

Новый /api/partner/coupons/get возвращает одинаковую ошибку, если:

• кода не существует;
• купон принадлежит другому партнеру.

Так API не раскрывает существование чужих данных.

Действие:

• проверить coupon_code;
• убедиться, что ведущие нули сохранены;
• проверить, что JWT относится к нужному клиентскому аккаунту.

Не создавайте пустую локальную карточку вместо существующей записи.

Внутренняя ошибка

10000

Означает внутреннюю ошибку сервиса.

Для методов чтения запрос можно повторить с ограничением частоты.

Для POST /api/partner/coupons/place нельзя слепо повторять запрос после неопределенного результата: сначала исключите возможность, что первый запрос был обработан, иначе можно создать дублирующий купон.

Если ошибка повторяется, передайте менеджеру:

• маршрут;
• время запроса;
• coupon_code, если он известен;
• верхнеуровневые date, path, time_ms;
• безопасный идентификатор запроса из логов партнера.

Не передавайте JWT, пароль или callback secret.

HTTP-ошибки нового API

HTTP 200 с code = 0 относится к бизнес-ошибкам и обрабатывается по error_code.

Ошибки callback

Callback не использует поле error_code. Получатель сообщает результат HTTP-ответом.

Для успешного подтверждения требуется именно HTTP 200. Ответы 201, 202 и 204 успехом не считаются и автоматически не повторяются.

Коды старого API

Старый POST /bet/place для rejected, no_data, block и error сохраняет общий:

error_code = 501

Точная причина находится в прямом массиве body[].

Историческое описание связывало 507 с общей серверной ошибкой. В актуальном контракте 1.2.0 код имеет определенное значение Insufficient balance; обрабатывайте его как недостаточный клиентский баланс. Код 540 остается историческим и не входит в актуальный OpenAPI-контракт.

Подробнее: «Совместимые старые маршруты».

Что показывать пользователю

Не показывайте пользователю:

• JWT;
• пароль;
• callback secret;
• внутренние stack trace;
• детали инфраструктуры;
• полный подписанный callback.

Контрольный список

• Проверяются HTTP-статус, code и error_code.
• error_message не используется как ключ логики.
• При отказе создания купон не сохраняется как принятый.
• Предварительный резерв суммы освобождается при подтвержденном отказе.
• body.changes обрабатывается как массив.
• Бизнес-коды 502–504 не путаются с HTTP-кодами.
• Ошибка 506 учитывается в корзине экспресса.
• Запрос создания не повторяется вслепую.
• Ошибки callback обрабатываются по отдельному HTTP-контракту.
• Секретные данные не попадают в сообщения и логи.

Следующий раздел: «Переход со старого API».