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

# Коды ошибок

> HTTP-статусы API Axottle, типовые причины и действия оператора.

Справочник ошибок API панели. Все эндпоинты живут под `/api/v1` и, за исключением публичных и setup-эндпоинтов, требуют авторизованной сессии администратора.

<Info>Для кого: администратор, SRE, разработчик интеграций. Требуемые права: зависят от эндпоинта.</Info>

<Note>
  Полный машинный каталог кодов ошибок в продукте пока не опубликован. Эта таблица описывает **наблюдаемое поведение API**: какие HTTP-статусы возвращаются, в каких ситуациях и что делать оператору. По мере стабилизации каталога страница будет расширяться.
</Note>

## HTTP-статусы

| Статус | Типовая причина                                                                                                                                                                                                            | Действие оператора                                                                                                                                                                                                                 |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Некорректный запрос: невалидный JSON, отсутствующие обязательные поля, неверные параметры                                                                                                                                  | Проверьте тело и параметры запроса по документации соответствующего эндпоинта                                                                                                                                                      |
| `401`  | Нет сессии или сессия просрочена: отсутствует/невалиден заголовок `Authorization: Bearer <session-token>`                                                                                                                  | Выполните вход заново (`POST /api/v1/auth/login`) и повторите запрос с новым токеном                                                                                                                                               |
| `403`  | Недостаточно прав **или** лицензионное ограничение: в деградированном режиме лицензии все изменяющие запросы отклоняются с сообщением о режиме «только чтение»; отдельные функции могут быть заблокированы планом лицензии | Проверьте статус лицензии (`axottle license status` или `GET /api/v1/license/status`). В деградированном режиме доступны поверхности восстановления: активация лицензии, самообновление панели, обновление агентов, аутентификация |
| `404`  | Ресурс не найден: несуществующий идентификатор, удалённый объект или неверный публичный токен в публичных ссылках                                                                                                          | Проверьте идентификатор/токен в URL; для публичных ссылок — актуальность ссылки                                                                                                                                                    |
| `409`  | Конфликт состояния: операция несовместима с текущим состоянием системы                                                                                                                                                     | Дождитесь завершения конкурирующей операции или устраните конфликт (примеры ниже)                                                                                                                                                  |
| `422`  | Ошибка валидации: данные синтаксически корректны, но не проходят бизнес-проверки                                                                                                                                           | Исправьте значения полей согласно сообщению об ошибке                                                                                                                                                                              |
| `5xx`  | Внутренняя ошибка панели или зависимого сервиса                                                                                                                                                                            | Смотрите логи: `axottle logs backend --tail 200`, затем `axottle doctor`; при повторении соберите support-бандл                                                                                                                    |

## Примеры конфликтов `409`

* **Бэкап уже выполняется** — по каждому профилю одновременно идёт не более одного запуска; повторный `POST /api/v1/backups/runs` для того же профиля вернёт `409`. Дождитесь завершения текущего запуска.
* **Автопривязка Remnawave отключена** — `POST /api/v1/setup/remnawave/bootstrap` возвращает `409`, если переменная `AXOTTLE_RW_BOOTSTRAP` не включена.
* **Вторая сессия Telegram-помощника** — helper-сессия для настройки уведомлений одиночная; параллельная попытка открыть вторую получает `409`.

## Особые случаи

### Тест Telegram-уведомлений

`POST /api/v1/notifications/telegram/test` — единственный эндпоинт уведомлений, который возвращает реальную ошибку доставки:

| Статус | Значение                                               | Действие                                                 |
| ------ | ------------------------------------------------------ | -------------------------------------------------------- |
| `400`  | Уведомления не настроены (нет токена бота или chat id) | Заполните настройки Telegram в панели                    |
| `502`  | Ошибка Telegram Bot API                                | Проверьте корректность токена бота и права бота в чате   |
| `504`  | Таймаут обращения к Telegram                           | Проверьте исходящую сетевую доступность с сервера панели |

В остальных случаях доставка уведомлений — best-effort: сбой отправки не ломает вызвавшую его операцию, ошибка фиксируется в audit-журнале.

### Деградированный режим лицензии

Если лицензия отсутствует, просрочена и не в grace-периоде, панель работает в режиме «только чтение»: `GET`-запросы проходят, изменяющие запросы получают `403`. Это не сбой, а штатная защита — восстановите лицензию, и запись снова заработает. Подробнее: [Лицензия](/ru/operations/license).

## Диагностика по шагам

<Steps>
  <Step title="Определите класс ошибки">
    `4xx` — проблема запроса, прав или состояния; `5xx` — проблема на стороне панели.
  </Step>

  <Step title="Для 401/403 проверьте сессию и лицензию">
    ```bash theme={null}
    curl -s https://panel.example.com/api/v1/license/status \
      -H "Authorization: Bearer <session-token>"
    ```
  </Step>

  <Step title="Для 5xx смотрите логи и Doctor">
    ```bash theme={null}
    axottle logs backend --tail 200
    axottle doctor
    ```
  </Step>
</Steps>

## Связанные страницы

<CardGroup cols={2}>
  <Card title="CLI axottle" icon="terminal" href="/ru/reference/cli">
    Команды `logs`, `doctor`, `license status`.
  </Card>

  <Card title="Лицензия" icon="key" href="/ru/operations/license">
    Grace-период и деградированный режим.
  </Card>
</CardGroup>

<Note>Проверено для версии Axottle текущей ветки. Дата проверки: 2026-07-11.</Note>