> ## 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.

# Ошибки и ограничения API

> Коды ошибок, различие между HTTP-сбоем и состоянием отчёта, CORS и обработка ответов прокси.

В интеграции проверяйте два уровня: HTTP-статус запроса и состояние отчёта в JSON. Они отвечают на разные вопросы: удалось ли выполнить запрос и есть ли пригодные данные за выбранный период.

## HTTP-ошибки приложения

Ошибки приложения возвращаются в JSON с полем `error`:

```json theme={null}
{
  "error": "invalid_range"
}
```

| HTTP | `error` | Причина | Что исправить |
| - | - | - | - |
| `400` | `invalid_month` | Некорректный месяц | Передайте `YYYY-MM` в пределах `2015-01`–`2099-12` |
| `400` | `invalid_period` | Неизвестный режим | Используйте `month`, `day`, `week` или `range` |
| `400` | `invalid_range` | Неверная дата, обратный диапазон, отсутствие `from` или `to`, более 31 дня | Проверьте существование дат, их порядок и длину периода с обеими границами |
| `400` | `invalid_parameters` | Параметры несовместимы с периодом | Оставьте `month` для месяца, `date` для дня/недели или `from`/`to` для диапазона |
| `400` | `invalid_server` | Неверный формат номера или ID, в том числе пустое значение | Передайте от 1 до 20 цифр либо полностью уберите параметр для общего списка |
| `404` | `server_not_found` | Сервер отсутствует в доступном каталоге | Проверьте номер или `guildId` по общему ответу |
| `404` | `not_found` | Неизвестный URL | Проверьте путь метода |
| `405` | `method_not_allowed` | Метод, отличный от `GET` или `HEAD` | Используйте `GET` для получения JSON |
| `500` | `internal_error` | Внутренняя ошибка приложения | Обработайте недоступность и повторите запрос позже |

Ошибки периода относятся к `/api/discord-statistics`. Для `/api/discord-icons` используются ошибки выбора сервера и общие HTTP-ошибки.

## Успешный запрос без готового отчёта

Следующие состояния передаются внутри ответа `200`, а не как HTTP-ошибка:

| Состояние | Где смотреть | Как отобразить |
| - | - | - |
| Отчёт ещё не собран | `status: "pending"` | «Нет данных» или «Ожидаем отчёт» |
| Отчёт устарел | `status: "stale"` | Сохранённое число, если есть, с отметкой об устаревании |
| Настроенный канал не найден | `status: "missing_channel"` | Сообщение о недоступности отчёта |
| Ошибка сбора или чтения | `status: "error"`, поле `error` сервера | Сообщение об ошибке отчёта |
| Общая выборка неполная | `complete: false` | Итог с указанием охвата `readyServers` из `totalServers` |

<Warning>
  `error` в корне HTTP-ошибки и `server.error` в отчёте имеют разный смысл. Первое описывает ошибку запроса, второе — состояние сбора или чтения данных конкретного сервера.
</Warning>

Полные правила обработки `null`, устаревших счётчиков и общих итогов — в разделе [«Данные и статусы»](/kalenich-stats/data-and-statuses).

## Ответы прокси

Прокси может вернуть `429` при превышении лимита запросов или `5xx` при недоступности сервиса. Тело такого ответа не обязательно будет JSON: возможен, например, HTML или обычный текст.

Для надёжной обработки:

* Сохраняйте HTTP-статус даже тогда, когда JSON разобрать не удалось.
* Не повторяйте неизменённые запросы с ошибками параметров `400` или отсутствующим сервером `404`.
* При сетевых сбоях, `429` и `5xx` используйте ограниченное число повторов с увеличением задержки; учитывайте `Retry-After`, если сервер его передал.
* Переиспользуйте результаты на своём сервере и не создавайте отдельный внешний запрос для каждого посетителя страницы.

Это рекомендации для клиента. Фиксированная квота запросов и обязательное наличие `Retry-After` публичной документацией сервиса не заданы.

## CORS и браузер

Междоменные браузерные запросы не включены. Вызов `fetch` со страницы на другом домене браузер может заблокировать, хотя тот же URL успешно открывается напрямую или работает из cURL.

```text theme={null}
Ваш браузер → ваш сервер → Kalenich Stats API
```

Выполняйте внешний запрос на своём сервере и отдавайте браузеру подготовленный результат. `mode: 'no-cors'` не решает задачу: содержимое ответа будет недоступно JavaScript.

## Частота обновления

API возвращает сохранённые отчёты. Повторный запрос не ускоряет сбор и не гарантирует новые данные. Ориентируйтесь на `refreshMinutes`, `generatedAt` и `status`, избегая частого опроса без необходимости.

Календарные правила и доступность архивных отчётов описаны в разделе [«Периоды и даты»](/kalenich-stats/periods).


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