# Разбор ошибок валидации

Ordinis старается давать понятные ошибки, но иногда нужна расшифровка.
Эта страница — справочник самых частых.

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

В UI ошибки появляются:
- **Инлайн под полем формы** — для конкретных полей (red text)
- **Тост в правом верхнем** — для общих ошибок (например, сеть)
- **Полноэкранный экран** — для серьёзных проблем (500 / 503)

Каждая ошибка имеет:
- **Код** (`webhook_status_invalid`, `record_not_active`) — машинный идентификатор
- **Сообщение** — человеческое описание на русском
- **Trace ID** (для серверных ошибок) — для передачи в ops

## Самые частые ошибки

### 422: «Поле X обязательно»

Что значит: схема справочника требует это поле, но ты его не заполнил.

Что делать: заполни и сохрани. Если поле кажется ненужным — это вопрос
к схеме справочника, обсуди с ревьюером (см. [schema drafts](../reviewer/schema-drafts.md)).

### 422: «Тип значения не соответствует схеме»

Что значит: например, в поле `mass_kg` (number) введён текст.

Что делать: проверь тип в hint'е под полем. Числовые поля принимают только
цифры (точка как разделитель десятых для дробей: `1234.5`).

### 422: «FK не найден»

Что значит: значение в поле со ссылкой (`x-references`) указывает на
запись, которой нет в целевом справочнике.

Что делать:
1. Открой целевой справочник (имя есть в hint'е поля)
2. Проверь, есть ли там запись с этим бизнес-ключом
3. Если нет — сначала добавь запись туда, потом возвращайся
4. Если есть, но закрыта — нужно её **активировать** или создать новую

### 409: «Бизнес-ключ уже существует»

Что значит: ты пытаешься создать запись с `code`, который уже занят
активной записью того же справочника.

Что делать:
- Выбери другой `code`
- Или: найди существующую запись и обнови её, а не создавай новую
- Или: закрой существующую (если она устарела) и создай заново

### 409: «Период действия пересекается»

Что значит: bitemporal модель не разрешает двум версиям одной записи
быть активными одновременно.

Что делать:
1. Найди активную версию того же бизнес-ключа
2. **Закрой её** (`valid_to = момент новой версии`), потом создавай новую
3. Или: укажи `valid_from` новой версии так, чтобы периоды не пересекались

См. [Закрытие записи](close-record.md).

### 403: «Нет доступа»

Что значит: у твоего пользователя нет прав на эту операцию или scope.

Что делать:
- Если справочник `RESTRICTED` — нужны права администратора, спроси у
  руководителя
- Если `INTERNAL` — нужен внутренний токен (не публичный)
- Если операция «approve schema draft» — это право ревьюера, не оператора
  (см. [reviewer guide](../reviewer/index.md))

### 401: «Требуется вход»

Что значит: твоя сессия истекла или нет валидного токена.

Что делать: войди заново через Keycloak. После logout / refresh всё должно
работать.

### 503: «Сервер временно недоступен»

Что значит: backend временно не отвечает (rolling restart, плановое
обслуживание, или сетевой сбой).

Что делать:
1. Подожди 30-60 секунд, нажми **«Повторить»**
2. Если повторяется > 5 минут — свяжись с ops
3. Никакие данные не пропали — сервер вернётся, твои изменения сохранены
   локально пока не отправил

### Network error / «Нет соединения»

Что значит: твой браузер не может достучаться до сервера. Чаще всего
проблема в твоей сети, не в Ordinis.

Что делать:
1. Проверь соединение (открой любой другой сайт)
2. Если корпоративная сеть — проверь VPN / прокси
3. Если изменения не сохранились — они **не пропадут**, попробуй
   повторить когда соединение вернётся

### «AxiosError: Request failed with status code 503» (raw)

Что значит: техническая ошибка, которая «убежала» в UI без friendly
обёртки. Это **баг UI**, не баг данных.

Что делать: сделай скриншот, передай в support с trace ID (если есть).

## Schema validation на стороне сервера

Когда ты сохраняешь запись, сервер валидирует её по JSON Schema справочника.
Если ошибка — увидишь подробности:

```
Validation failed:
- /satellite_type: must be one of ['OPERATIONAL', 'TESTING', 'DECOMMISSIONED']
- /mass_kg: must be number, got string
- /name: required property missing
```

Каждая строка — отдельная проблема. Поправь все, сохрани заново.

## Если не помогает

1. **Скриншот** — снимок экрана со всеми видимыми деталями ошибки
2. **Trace ID** — если есть в сообщении, скопируй
3. **Время** — точное время, когда возникла
4. **Что ты делал** — последняя последовательность действий
5. Передай это команде поддержки. По этим данным они смогут восстановить
   контекст через [журнал аудита](audit-log.md) и серверные логи.

## Что НЕ нужно делать

- ❌ **Очищать кэш браузера / cookies** — это сломает сессию, ошибку не уберёт
- ❌ **Открывать в инкогнито** — то же самое
- ❌ **Менять JSON вручную в DevTools** — данные не сохранятся всё равно,
      но можешь напугать себя
- ❌ **Заводить дубликат записи «чтобы попробовать»** — если первая не
      сохранилась, она и не сохранилась, дубликат не появится