> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arzguard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Запросы, ответы и ошибки

> Базовый URL Guard Forum, форматы тела запроса, JSON-ответы, HTTP-статусы и обработка ошибок XenForo.

Базовый адрес API Guard Forum:

```text theme={null}
https://forum.arzguard.com/api/
```

Путь метода добавляется после `/api/`. Например, `GET threads/` вызывается по адресу `https://forum.arzguard.com/api/threads/`; номер страницы можно добавить как `?page=1`.

> [!NOTE]
>
> Список тем `GET threads/` содержит `threads` и `pagination`. Структура успешного ответа зависит от метода и прав доступа.

## Формат запроса

Все передаваемые данные используют **UTF-8**. Ключ авторизации обязателен в каждом запросе:

```http theme={null}
XF-Api-Key: YOUR_API_KEY
Accept: application/json
```

`YOUR_API_KEY` — условное обозначение. Подробнее о типах ключей и контексте пользователя — на странице [«Авторизация»](/guard-forum/authentication).

| Ситуация | Как передавать параметры |
| - | - |
| GET-запрос | В query string после `?` |
| Запрос с обычным телом | `application/x-www-form-urlencoded` |
| Загрузка файла | `multipart/form-data` |

XenForo также допускает параметры в query string у запросов с телом, но рекомендует передавать их в теле. Выбор метода и список допустимых параметров определяет конкретный endpoint.

> [!WARNING]
>
> JSON — формат обычного ответа API. Для тела запроса используйте форму: `application/x-www-form-urlencoded` либо `multipart/form-data`. Не подменяйте их `application/json`.

В JavaScript обычную форму можно подготовить через `URLSearchParams`, а форму с файлом — через `FormData`. При использовании `FormData` клиент должен самостоятельно сформировать заголовок с `boundary`; не задавайте `Content-Type` вручную без этой границы.

## Ответы и HTTP-статусы

Обычные ответы возвращаются в JSON. Исключение — методы, явно запрашивающие бинарный файл, например скачивание вложения: такой ответ нужно обрабатывать как файл, а не через `response.json()`.

| HTTP | Значение | Действие клиента |
| - | - | - |
| `200` | Запрос выполнен успешно | Разобрать ответ по схеме метода |
| `3xx` | Перенаправление | Проверить конечный адрес и правила перенаправлений клиента |
| `4xx` | Ошибка запроса или доступа | Разобрать `errors` и исправить причину |
| `5xx` | Сервер не смог обработать запрос | Обработать сбой отдельно от ошибок параметров |

Стандартный успешный ответ XenForo использует HTTP `200`. Не определяйте успех по наличию единого поля вроде `success`: структура успешного ответа зависит от метода.

Для инфраструктурного сбоя обработчик должен учитывать ситуацию, когда JSON разобрать не удалось. Например, ответ внешнего прокси может отличаться от стандартного тела ошибки XenForo.

## Структура ошибки

Стандартный ответ XenForo содержит массив `errors` с одной или несколькими ошибками. Ниже — условный пример ошибки неизвестного ключа:

```json theme={null}
{
  "errors": [
    {
      "code": "api_key_not_found",
      "message": "API key provided in request was not found.",
      "params": []
    }
  ]
}
```

| Поле | Для чего использовать |
| - | - |
| `errors` | Перечень ошибок запроса; обрабатывайте все элементы |
| `errors[].code` | Машиночитаемый код для логики приложения |
| `errors[].message` | Текстовое описание для человека |
| `errors[].params` | Дополнительные параметры ошибки; набор зависит от причины, может быть пустым |

Текст `message` может меняться или переводиться. Для распознавания ситуации используйте `code`, а HTTP-статус сохраняйте как отдельную характеристику. Единого исчерпывающего списка кодов для всех ситуаций нет: они зависят от метода и причины ошибки.

## Пример запроса на чтение

Оба примера обращаются к `GET threads/`; ключу нужен scope `thread:read`. Они предназначены для серверного окружения с заранее настроенной переменной `FORUM_API_KEY`. Примеры не содержат реального ключа и не включают обход прав пользователя.

**cURL**

```bash theme={null}
curl --silent --show-error \
  --header "XF-Api-Key: $FORUM_API_KEY" \
  --header 'Accept: application/json' \
  'https://forum.arzguard.com/api/threads/?page=1'
```

По умолчанию cURL выведет тело ответа, в том числе JSON ошибки. Для диагностики HTTP-статуса можно добавить `--write-out '\nHTTP %{http_code}\n'`. Не включайте вывод заголовков запроса с ключом в публичные логи.

**Node.js**

```javascript theme={null}
const apiKey = process.env.FORUM_API_KEY;
if (!apiKey) throw new Error('Не задана FORUM_API_KEY');

const response = await fetch('https://forum.arzguard.com/api/threads/?page=1', {
  headers: {
    'XF-Api-Key': apiKey,
    Accept: 'application/json'
  },
  redirect: 'error'
});

let data;
try {
  data = await response.json();
} catch {
  throw new Error(`HTTP ${response.status}: ответ не является JSON`);
}

if (!response.ok) {
  const codes = Array.isArray(data.errors)
    ? data.errors.map(error => error.code).filter(Boolean)
    : [];
  throw new Error(`HTTP ${response.status}: ${codes.join(', ') || 'ошибка API'}`);
}

const threads = data.threads;
const pagination = data.pagination;
// Используйте threads и pagination в своей серверной интеграции.
```

Здесь перенаправления намеренно отключены, а диагностическое сообщение содержит HTTP-статус и коды ошибок без ключа и полного тела ответа. Ошибки сети или отклонённого перенаправления обрабатываются вызывающим кодом.

## Пагинация

Пагинация зависит от метода. Если ответ содержит `pagination`, обрабатывайте страницы по её метаданным и описанию endpoint. Не считайте параметр `page` или поле `pagination` обязательными для любого списка.

В постраничных ответах `pagination` содержит `current_page`, `last_page`, `per_page`, `shown` и `total`. При пустой коллекции текущая и последняя страницы могут быть `0`. Если запрошенная страница выходит за пределы непустой выдачи, API возвращает ошибку `invalid_page` с параметром `max`.

> [!TIP]
>
> Обработку HTTP и `errors` удобно вынести в общий клиент. Схему успешного ответа и правила пагинации оставьте на уровне конкретного метода: они различаются.

> **[Авторизация](/guard-forum/authentication)**
>
> Ключи, scopes и права пользователя, от имени которого работает интеграция.

> **[Контракт REST API XenForo](https://docs.xenforo.com/manual/reference/rest-api#accessing-the-api)**
>
> Официальное руководство по форматам запросов, ответов и ошибок.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.