---
id: response-format
title: Общий формат ответа Sport Line API
description: Описание основных форматов успешных ответов и ошибок, возвращаемых методами Sport Line API.
version: v1
language: ru
---

# Общий формат ответа Sport Line API


## Какие форматы ответа встречаются

Sport Line API может вернуть три основных типа JSON-ответа:

1. Успешную оболочку с данными в `body`.
2. Служебное сообщение метода `event` внутри `body.message`.
3. Ошибку с полями `error_code` и `error_message` без обычной оболочки.

```text
ответ Sport Line API
├── status + page + body       → данные или пустая выборка
├── status + page + body.message → состояние конкретного матча
└── error_code + error_message → ошибка доступа или параметров
```

Клиент должен различать эти структуры по полям ответа, а не ожидать один универсальный
тип `body`.

## Успешная оболочка

Обычный успешный ответ содержит три поля верхнего уровня:

```json
{
  "status": 1,
  "page": "/v1/sports",
  "body": [
    {
      "id": 1,
      "name": "Футбол",
      "counter": 39
    }
  ]
}
```

| Поле | Тип | Описание |
|---|---|---|
| `status` | number | Статус формирования ответа; в подтверждённых успешных ответах равен `1` |
| `page` | string | Название метода, сформировавшего ответ |
| `body` | array или object | Данные метода, пустая выборка или служебное сообщение |

В документации не подтверждены другие значения `status`. Не создавайте бизнес-логику
на предположениях о значениях `0`, `2` или других неподтверждённых статусах.

## Поле `status`

В обычном успешном ответе:

```json
{
  "status": 1
}
```

Однако `status: 1` означает, что API сформировал корректный ответ. Это значение не
гарантирует, что `body` содержит запрошенные данные.

Например, сообщение о недоступном матче также возвращается со `status: 1`:

```json
{
  "status": 1,
  "page": "/v1/event",
  "body": {
    "message": "Game id finished"
  }
}
```

Поэтому после проверки `status` всегда анализируйте тип и содержимое `body`.

## Поле `page`

`page` показывает, какой метод сформировал ответ.

| Метод | Подтверждённое значение `page` |
|---|---|
| `menu` | `/v1/menu` |
| `sports` | `/v1/sports` |
| `countries` | `/v1/countries` |
| `tournaments` | `/v1/tournaments` |
| `events` | `/v1/events` |
| `event` | `/v1/event` |
| `topmatches` | `/v1/topmathes` |
| `toplist` | `/v1/toplist` |
| `search` | `/v1/search` |

В ответе `topmatches` фактически используется строка `/v1/topmathes` без буквы `c`.
Это текущее значение API, а не путь, по которому нужно выполнять запрос.

Не используйте `page` для построения URL или выбора следующего метода. Путь запроса уже
известен клиенту, а `page` удобно сохранять только для диагностики и журналирования.

## Поле `body`

Тип и вложенная структура `body` зависят от метода.

| Метод | Тип `body` | Содержимое |
|---|---|---|
| `menu` | array | Виды спорта со вложенными странами и турнирами |
| `sports` | array | Виды спорта |
| `countries` | array | Страны выбранного вида спорта |
| `tournaments` | array | Турниры выбранной страны и вида спорта |
| `events` | array | Турниры и вложенные списки матчей |
| `event` | object | Подробный объект одного матча или субматча |
| `topmatches` | array | Плоский список топ-матчей |
| `toplist` | array | Плоский список матчей выбранного вида спорта |
| `search` | array | Плоский список найденных матчей |

Для метода `event` объект `body` также может содержать только поле `message`. Эту
структуру нужно проверять до разбора полей матча.

## Пример ответа со списком

Большинство методов возвращает массив в `body`:

```json
{
  "status": 1,
  "page": "/v1/countries",
  "body": [
    {
      "id": 1,
      "name": "Международные",
      "sport_id": 1,
      "counter": 8
    }
  ]
}
```

Структура элементов массива зависит от метода. Нельзя обрабатывать `menu`, `events` и
`search` одним и тем же парсером только потому, что их `body` является массивом.

## Пример ответа конкретного матча

Метод `event` возвращает объект матча непосредственно в `body`:

```json
{
  "status": 1,
  "page": "/v1/event",
  "body": {
    "game_id": 746146992,
    "game_mid": 746146992,
    "sport_id": 1,
    "opp_1_name": "Арсенал",
    "opp_2_name": "Ковентри Сити",
    "game_oc_counter": 278
  }
}
```

Не ожидайте массив внутри `body` метода `event` и не применяйте к нему парсер метода
`events`.

## Пустая выборка

Если по условиям запроса нет доступных данных, API может вернуть пустой массив:

```json
{
  "status": 1,
  "page": "/v1/events",
  "body": []
}
```

Пустой `body` не обязательно является ошибкой. Он может означать, что:

- для выбранного вида спорта или турнира сейчас нет матчей;
- в выбранном типе линии нет доступных событий;
- поиск не нашёл совпадений;
- навигационный раздел сейчас пуст.

Показывайте пользователю пустое состояние, а не системную ошибку. Не подставляйте ранее
сохранённые данные как актуальные только потому, что новый ответ пуст.

## Служебное сообщение в `body.message`

Некоторые состояния метода `event` возвращаются как объект с полем `message` внутри
обычной оболочки ответа.

### Матч не найден

```json
{
  "status": 1,
  "page": "/v1/event",
  "body": {
    "message": "Game not found"
  }
}
```

### Матч больше недоступен

```json
{
  "status": 1,
  "page": "/v1/event",
  "body": {
    "message": "Game id finished"
  }
}
```

`Game id finished` не сообщает, почему матч исчез. Он мог перейти из Prematch в Live с
новым `game_id`, быть отменён или стать недоступным по другой причине.

После получения сообщения:

1. Не пытайтесь разобрать `body` как объект матча.
2. Прекратите частое обновление старого `game_id`.
3. Обновите список матчей методом `events`.
4. Не присваивайте матчу статус «завершён», «начался» или «отменён» только на основании
   текста сообщения.

## Формат ошибки API

Ошибки доступа и проверки параметров возвращаются без полей `status`, `page` и `body`:

```json
{
  "error_code": 100,
  "error_message": "Invalid Package"
}
```

| Поле | Тип | Описание |
|---|---|---|
| `error_code` | number | Числовой код категории ошибки |
| `error_message` | string | Текстовое описание причины |

Не полагайтесь только на HTTP-статус. После разбора JSON отдельно проверяйте наличие
`error_code` и `error_message`.

Полный список подтверждённых ошибок и рекомендации находятся в документе
[«Обработка ошибок»](../getting-started/error-handling.md).

## Рекомендуемый порядок разбора ответа

```text
получить HTTP-ответ
        ↓
разобрать JSON
        ↓
есть error_code/error_message?
  ├── да  → обработать ошибку API
  └── нет
        ↓
есть status/page/body?
  ├── нет → неизвестный формат ответа
  └── да
        ↓
body содержит message?
  ├── да  → обработать состояние метода event
  └── нет
        ↓
body — пустой массив?
  ├── да  → показать пустое состояние
  └── нет → разобрать данные по схеме запрошенного метода
```

Пример общей проверки на JavaScript:

```js
function parseSportApiResponse(payload) {
  if (
    payload &&
    typeof payload === 'object' &&
    !Array.isArray(payload) &&
    payload.error_code !== undefined
  ) {
    return {
      type: 'error',
      code: payload.error_code,
      message: payload.error_message
    };
  }

  if (
    !payload ||
    typeof payload !== 'object' ||
    Array.isArray(payload) ||
    payload.status === undefined ||
    typeof payload.page !== 'string' ||
    !('body' in payload)
  ) {
    return { type: 'unknown-response', payload };
  }

  if (
    payload.body &&
    !Array.isArray(payload.body) &&
    typeof payload.body === 'object' &&
    typeof payload.body.message === 'string'
  ) {
    return { type: 'event-message', message: payload.body.message };
  }

  if (Array.isArray(payload.body) && payload.body.length === 0) {
    return { type: 'empty', data: [] };
  }

  return {
    type: 'data',
    page: payload.page,
    data: payload.body
  };
}
```

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

## Что логировать

Для диагностики сохраняйте:

- время запроса и часовой пояс;
- запрошенный метод;
- тип линии `live` или `line`;
- HTTP-статус;
- значение `page`;
- `error_code` и `error_message`, если они есть;
- `body.message`, если оно есть;
- использованные ID и язык.

Не сохраняйте действующий API-ключ в публичных журналах, сообщениях об ошибках или
клиентской аналитике.

## Практические правила интеграции

1. Всегда сначала разбирайте верхний уровень JSON.
2. Проверяйте `error_code` до обработки обычной оболочки.
3. Не считайте `status: 1` гарантией наличия данных.
4. Учитывайте, что `body` может быть массивом или объектом.
5. Проверяйте `body.message` до разбора объекта матча.
6. Обрабатывайте пустой массив как отсутствие данных, а не как системную ошибку.
7. Выбирайте схему данных по запрошенному методу, а не только по значению `page`.
8. Не полагайтесь только на HTTP-статус при определении ошибки API.

## Связанные документы

- [Быстрый старт](../getting-started/quick-start.md)
- [Авторизация и доступ](../getting-started/authentication-and-access.md)
- [Обработка ошибок](../getting-started/error-handling.md)
- [Единый справочник полей](field-reference.md)
- [Методы Sport Line API](../api-reference/README.md)
