---
id: response-format
title: Sport Line API Response Format
description: Description of successful response and error formats returned by Sport Line API methods.
version: v1
language: en
---

# Sport Line API Response Format

## Response Structures

Sport Line API may return three main types of JSON response:

1. A successful response envelope with data in `body`.
2. An `event` method service message in `body.message`.
3. An error containing `error_code` and `error_message` without the standard envelope.

```text
Sport Line API response
├── status + page + body         → data or an empty result set
├── status + page + body.message → state of a specific match
└── error_code + error_message   → access or parameter error
```

The client must distinguish these structures by their fields instead of expecting one
universal `body` type.

## Successful Response Envelope

A standard successful response contains three top-level fields:

```json
{
  "status": 1,
  "page": "/v1/sports",
  "body": [
    {
      "id": 1,
      "name": "Football",
      "counter": 39
    }
  ]
}
```

| Field | Type | Description |
|---|---|---|
| `status` | number | Response generation status; confirmed successful responses return `1` |
| `page` | string | Name of the method that generated the response |
| `body` | array or object | Method data, an empty result set, or a service message |

No other `status` values have been confirmed in this documentation. Do not build
business logic based on assumptions about `0`, `2`, or other unconfirmed values.

## The `status` Field

A standard successful response contains:

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

However, `status: 1` means that the API generated a valid response. It does not
guarantee that `body` contains the requested data.

For example, an unavailable-match message also returns `status: 1`:

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

After checking `status`, always inspect the type and contents of `body`.

## The `page` Field

`page` identifies the method that generated the response.

| Method | Confirmed `page` value |
|---|---|
| `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` |

The `topmatches` response currently uses `/v1/topmathes`, without the letter `c`. This
is the actual API value, not the path used to make the request.

Do not use `page` to construct URLs or choose the next method. The client already knows
the requested path. The `page` value is useful only for diagnostics and logging.

## The `body` Field

The type and nested structure of `body` depend on the method.

| Method | `body` type | Contents |
|---|---|---|
| `menu` | array | Sports with nested countries and tournaments |
| `sports` | array | Sports |
| `countries` | array | Countries for the selected sport |
| `tournaments` | array | Tournaments for the selected country and sport |
| `events` | array | Tournaments with nested match lists |
| `event` | object | Detailed object for one match or submatch |
| `topmatches` | array | Flat top-match list |
| `toplist` | array | Flat match list for the selected sport |
| `search` | array | Flat list of matching results |

For `event`, the `body` object may also contain only a `message` field. Check for this
structure before parsing match fields.

## List Response Example

Most methods return an array in `body`:

```json
{
  "status": 1,
  "page": "/v1/countries",
  "body": [
    {
      "id": 1,
      "name": "International",
      "sport_id": 1,
      "counter": 8
    }
  ]
}
```

The structure of each array item depends on the method. Do not process `menu`, `events`,
and `search` with the same parser simply because their `body` fields are arrays.

## Specific Match Response Example

The `event` method returns the match object directly in `body`:

```json
{
  "status": 1,
  "page": "/v1/event",
  "body": {
    "game_id": 746146992,
    "game_mid": 746146992,
    "sport_id": 1,
    "opp_1_name": "Arsenal",
    "opp_2_name": "Coventry City",
    "game_oc_counter": 278
  }
}
```

Do not expect an array inside an `event` response's `body`, and do not apply the
`events` parser to it.

## Empty Result Set

When no data is available for the request conditions, the API may return an empty array:

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

An empty `body` is not necessarily an error. It may mean that:

- the selected sport or tournament currently has no matches;
- the selected sports line type has no available events;
- the search found no matches;
- the navigation section is currently empty.

Show an empty state to the user instead of a system error. Do not present previously
stored data as current merely because the new response is empty.

## Service Message in `body.message`

Some `event` states are returned as an object containing a `message` field inside the
standard response envelope.

### Match Not Found

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

### Match Is No Longer Available

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

`Game id finished` does not explain why the match disappeared. It may have moved from
Prematch to Live with a new `game_id`, been cancelled, or become unavailable for
another reason.

After receiving this message:

1. Do not parse `body` as a match object.
2. Stop frequently updating the old `game_id`.
3. Refresh the match list using `events`.
4. Do not assign the match a “finished,” “started,” or “cancelled” status based only on
   the message text.

## API Error Format

Access and parameter validation errors are returned without `status`, `page`, or `body`:

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

| Field | Type | Description |
|---|---|---|
| `error_code` | number | Numeric error category code |
| `error_message` | string | Text describing the cause |

Do not rely only on the HTTP status. After parsing the JSON, separately check for
`error_code` and `error_message`.

The complete list of confirmed errors and handling recommendations is available in
[Error Handling](../getting-started/error-handling.md).

## Recommended Response Parsing Order

```text
receive HTTP response
        ↓
parse JSON
        ↓
error_code/error_message present?
  ├── yes → handle API error
  └── no
        ↓
status/page/body present?
  ├── no  → unknown response format
  └── yes
        ↓
body contains message?
  ├── yes → handle event method state
  └── no
        ↓
body is an empty array?
  ├── yes → show an empty state
  └── no  → parse data using the requested method's schema
```

General JavaScript validation example:

```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
  };
}
```

After this general validation, pass the data to the parser for the specific method.

## What to Log

For diagnostics, record:

- request time and time zone;
- requested method;
- sports line type: `live` or `line`;
- HTTP status;
- `page` value;
- `error_code` and `error_message`, if present;
- `body.message`, if present;
- IDs and language used in the request.

Do not store an active API key in public logs, error messages, or client-side analytics.

## Practical Integration Rules

1. Always parse the top level of the JSON first.
2. Check for `error_code` before processing the standard envelope.
3. Do not treat `status: 1` as a guarantee that data is present.
4. Account for `body` being either an array or an object.
5. Check for `body.message` before parsing a match object.
6. Treat an empty array as no data, not as a system error.
7. Choose the data schema according to the requested method, not only the `page` value.
8. Do not rely only on the HTTP status when detecting an API error.

## Related Documents

- [Quick Start](../getting-started/quick-start.md)
- [Authentication and Access](../getting-started/authentication-and-access.md)
- [Error Handling](../getting-started/error-handling.md)
- [Field Reference](field-reference.md)
- [Sport Line API Methods](../api-reference/README.md)
