# Коды ошибок

> Коды отказов платформы: когда возникают и что делать.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

Ошибка платформы приходит в форме `{ "error": "…", "code": "…", "hint": "…" }`. Ветвиться
можно только по `code` и `limit.code`: тексты `error` и `hint` меняются, коды нет. Тексты
английские, их читает агент.

## Доступ и ключи

| Код | Когда | Что делать |
|---|---|---|
| `unauthorized` | ключа нет или он недействителен | `xflow login`; в CI проверить `XFLOW_TOKEN` |
| `forbidden` | у ключа нет нужного права, или доступ к проекту только на просмотр | право включает владелец ключа в настройках платформы, уровень «Редактирование» выдают в окне «Пригласить» проекта |
| `not_found` | проекта, приложения или функции нет, либо проект вам закрыт | проверить id; ключ мог быть от другой организации: `xflow org` |
| `invalid_request` | запрос неверен; текст называет, что именно | исправить по `hint` |
| `invalid_request` | на платформе ревизия новее той, от которой вы работали | `xflow pull --into ./server-copy`, слить изменения в git, повторить |
| `invalid_request` | переменная уровня организации, а часть её проектов вам закрыта | `xflow env set … --scope project` или попросить владельца организации |
| `confirm_required` | действие необратимо и нужно явное согласие | повторить с согласием: `--allow-removals`, `--yes` |
| `conflict` | состояние успело измениться: имя занято, идёт перенос базы | прочитать текст и повторить |
| `rate_limited` | слишком много запросов с ключа или адреса | подождать столько, сколько в `Retry-After` |
| `outdated_cli` | версия CLI ниже минимальной | `xflow update`, до этого ничего не заработает |
| `internal` | сбой на стороне платформы | повторить позже |

Доступ к проектам и права ключа: [Участники и доступ](https://docs.getxflow.com/platform/access.md), [Подключение агента](https://docs.getxflow.com/agent/setup.md).

## Сборка и проверка

Отказ проверки приходит списком `issues`, у каждого нарушения код, файл и строки. Сборка не
начинается, попытка ничего не стоит. Правила: [Проверка перед сборкой](https://docs.getxflow.com/develop/build-check.md).

| Код | Когда | Что делать |
|---|---|---|
| `no-package-json`, `bad-package-json`, `no-build-script` | нет `package.json`, он не читается или в нём нет скрипта сборки | вернуть `package.json` и скрипт из `build.command` |
| `not-vite`, `ssr-framework`, `forbidden-directory` | не Vite или серверный фреймворк | приложение это Vite SPA, код в `src/` |
| `no-index-html`, `no-entry-point` | нет `index.html` или `src/main.tsx` (`.ts`, `.jsx`, `.js`) | вернуть точку входа шаблона |
| `bad-build-dir` | `build.dir` указывает за пределы папки | путь внутри папки приложения: [xflow.json](https://docs.getxflow.com/reference/xflow-json.md) |
| `bad-file-name` | имя файла не латиницей | переименовать: латиница, цифры, пробел и `. - _ ~` |
| `secret-in-source` | в исходниках ключ или токен | убрать в [переменные](https://docs.getxflow.com/platform/secrets.md) функции |
| `server-only-api` | во фронтенде `fs`, `http`, `express` и подобные | серверная часть живёт в функциях |
| `hardcoded-function-url` | адрес функции вписан в код | звать через `xflow.functions.invoke` |
| `no-alert`, `no-confirm`, `no-prompt`, `no-console-log` | системные окна или `console.log` вне `src/components/ui` и `blocks` | диалоги шаблона; `console.error` разрешён, но в логи не попадает |
| `missing-provider` | библиотеке нужен провайдер, а он не подключён | подключить провайдер, иначе белый экран |
| `missing-ui-component` | импорт компонента из `@/components/ui`, которого нет | вернуть компонент или убрать импорт |
| `platform-file-changed`, `platform-file-removed`, `template-wiring-broken` | изменён или удалён файл платформы, сломана проводка шаблона | вернуть оригинал командой из текста отказа: [Шаблон](https://docs.getxflow.com/develop/template.md) |
| `theme-token-removed`, `theme-token-unmapped` | удалены токены темы, которыми красят компоненты шаблона | менять значения, а не имена, или удалить и эти компоненты |
| `functions-in-app` | функция лежит в папке приложения | перенести в `functions/<имя>/` корня, выкатить `xflow deploy functions` |
| `no-xflow-json`, `bad-xflow-json` | нет `xflow.json` в корне или он неверен | `xflow link <id>`; поправить по тексту |
| `bad-function-name` | имя функции не по правилам | строчная латиница, цифры, дефис, до 41 символа |
| `binding-without-function` | у имени в `functions` нет папки `functions/<имя>/` с `index.ts` | добавить функцию или убрать запись |
| `unknown-caller` | зовущий не приложение этого проекта | указать папку приложения из `apps/` |
| `env-name-not-literal` | имя переменной собрано выражением | писать `process.env.ИМЯ` буквально |
| `unknown-min-role` | `minRole` называет роль, которой нет | роль из шкалы платформы: [Функции](https://docs.getxflow.com/platform/functions.md) |

Пометки сборку не останавливают, но до слова «готово» их исправляют: `default-title`
(заголовок из шаблона), `default-icon` (нет иконки), `access-export-ignored` (`exports.access`
ничего не значит, зовущие задаются в `xflow.json`).

## База

| Код | Когда | Что делать |
|---|---|---|
| `invalid_request` | миграция удаляет данные без `--allow-destructive`, или изменён уже применённый файл | для удаления флаг и право на ключе; правку писать новой миграцией |
| `forbidden` | у ключа нет права удалять данные или переносить базу | право включает владелец ключа |
| `forbidden`, `limit.code: db_write_locked` | объём данных вышел за лимит тарифа, запись в базу выключена | удалить лишние строки: запись вернётся в течение часа; или поднять тариф |

Подробнее: [База данных](https://docs.getxflow.com/platform/database.md).

## Функции

Отказ при вызове функции приходит в поле `reason` ответа, в коде приложения это `code` у `XFlowError`.

| Код | Статус | Когда | Что делать |
|---|---|---|---|
| `not_bound` | 404 | приложение не указано в `callers` функции | добавить папку в `xflow.json`, `xflow deploy functions` |
| `not_found` | 404 | функция не выкачена | `xflow deploy functions` |
| `login_required`, `invalid_credential` | 401 | посетитель не вошёл или вход устарел | войти заново |
| `no_access` | 403 | у человека нет доступа к приложению | доступ даёт человек: [Участники и доступ](https://docs.getxflow.com/platform/access.md) |
| `role_too_low` | 403 | роль ниже `minRole` функции | роль выше или другой порог |
| `functions_stopped` | 403 | функции организации остановлены | см. «Тариф» ниже, код тут не поможет |
| `bad_min_role` | 500 | `minRole` с неизвестной ролью | исправить `minRole` в коде функции |
| `rate_limited` | 429 | слишком много вызовов сразу | вызывать пачками, не все элементы списка параллельно |
| `unavailable` | 503 | платформа не смогла проверить вызов | повторить позже |

Падения самого кода смотрят в `xflow functions logs <имя>`.

## Тариф

Отказ по тарифу приходит как `forbidden` с полем `limit`: `{ "code": "limit_apps", "used": 1, "limit": 1 }`.
Повтор, переименование и правка кода не помогают: лимит снимает владелец организации.
Лимиты и занятое: `xflow whoami`. Подробнее: [Тариф](https://docs.getxflow.com/platform/billing.md).

| `limit.code` | Когда | Что делать |
|---|---|---|
| `limit_apps`, `limit_functions`, `limit_pages`, `limit_connections` | кончились приложения, функции, страницы или активные подключения | удалить ненужное, отключить неиспользуемое подключение или поднять тариф |
| `limit_projects` | 100 проектов в организации | удалить ненужные проекты |
| `limit_seats` | кончились места для людей, считая приглашения | поднять тариф |
| `limit_builds` | кончились сборки месяца | ждать даты обнуления из текста или поднять тариф |
| `limit_builds_concurrent` | идёт максимум сборок одновременно | дождаться их и повторить |
| `plan_no_schedules`, `limit_schedules`, `limit_schedule_interval` | расписаний нет на тарифе, кончились или запуск чаще разрешённого | реже запускать или поднять тариф; cron тут ни при чём |
| `db_write_locked` | база больше лимита | см. «База» выше |
| `functions_stopped` | кончились минуты функций или подписка не оплачена | оплатить или перейти на тариф выше, функции вернутся сразу |
| `subscription_blocked` | организация заморожена за неоплату: отказ на всё, кроме `xflow whoami` | владелец оплачивает счёт в настройках организации |
| `billing_unavailable` | платформа не смогла проверить тариф | повторить позже |

## Файлы

Загрузка файлов из кода функции отвечает своими кодами: [Файлы](https://docs.getxflow.com/platform/storage.md).

| Код | Когда | Что делать |
|---|---|---|
| `quota_exceeded` | хранилище организации заполнено | удалить ненужные файлы или поднять тариф |
| `file_too_large` | файл больше 200 МБ | уменьшить файл |
| `duplicate_name` | имя в этой папке занято | `overwrite: true` заменяет файл, адрес остаётся |
| `forbidden_type` | страницы, скрипты, исполняемые файлы | хранилище только для ресурсов приложения |
| `not_uploaded` | подтверждение до конца загрузки | подтверждать после завершения PUT |
| `invalid_name` | недопустимое имя файла | переименовать |