---
url: https://docs.snapotter.com/ru/api/errors.md
description: Формат тела ошибки, стабильные коды и что делать в каждом случае.
---

# Коды ошибок

Каждый ответ JSON с ошибкой имеет одинаковую структуру:

```json
{
  "error": "Job not found",
  "code": "NOT_FOUND",
  "requestId": "req-42"
}
```

| Поле | Всегда присутствует | Значение |
|-------|----------------|---------|
| `error` | Да | Понятное человеку сообщение. Его можно показывать пользователям. Не разбирайте его программно. |
| `code` | Да | Стабильный машиночитаемый код. Ветвите логику по нему. |
| `requestId` | Да | Идентификатор этого запроса на сервере. Указывайте его, когда сообщаете о проблеме: он совпадает с записью в журнале сервера. |
| `details` | Иногда | Дополнительный контекст для некоторых ошибок 4xx, например сообщение о проверке. |

Сообщения могут меняться между релизами. Коды не меняются, поэтому пишите клиентскую логику на основе `code`.

## Коды по статусу HTTP

Если маршрут не задаёт собственный код, сервер выводит его из статуса:

| Статус HTTP | `code` |
|-------------|--------|
| 400 | `BAD_REQUEST` |
| 401 | `AUTH_REQUIRED` |
| 403 | `FORBIDDEN` |
| 404 | `NOT_FOUND` |
| 409 | `CONFLICT` |
| 413 | `PAYLOAD_TOO_LARGE` |
| 415 | `UNSUPPORTED_MEDIA_TYPE` |
| 422 | `UNPROCESSABLE_ENTITY` |
| 429 | `RATE_LIMITED` |
| 500 | `INTERNAL_ERROR` |
| 501 | `NOT_IMPLEMENTED` |
| 503 | `SERVICE_UNAVAILABLE` |
| 507 | `INSUFFICIENT_STORAGE` |

Любой другой статус 4xx получает `BAD_REQUEST`, а любой другой 5xx получает `INTERNAL_ERROR`.

Маршрут может задать более конкретный код, и тогда ответ содержит именно его. Например, инструмент, который не может запуститься из-за отсутствующего пакета ИИ, возвращает код, специфичный для функции. Эти коды описаны вместе с функцией, которая их вызывает.

## Аутентификация и доступ

| `code` | Статус | Что делать |
|--------|--------|------------|
| `AUTH_REQUIRED` | 401 | Передайте `Authorization: Bearer <token>` с токеном сессии или ключом API (`si_...`). |
| `FORBIDDEN` | 403 | Учётные данные действительны, но у них нет нужного разрешения. Попросите администратора выдать разрешение. |
| `MUST_CHANGE_PASSWORD` | 403 | Учётная запись должна сменить пароль, прежде чем вызывать другие эндпоинты. Вызовите `POST /api/auth/change-password` с токеном сессии, затем повторите запрос. |
| `USER_DISABLED` | 403 | Учётная запись отключена. Администратор должен снова включить её. |
| `LOGIN_THROTTLED` | 429 | Слишком много неудачных попыток входа. Подождите, прежде чем пробовать снова. |
| `VALIDATION_ERROR` | 400 | Тело запроса или параметры не прошли проверку. `details` указывает на проблему. |

Учётная запись администратора первого запуска: `admin` с паролем `admin`, если только `DEFAULT_USERNAME` или `DEFAULT_PASSWORD` не изменили их. Если не задано `SKIP_MUST_CHANGE_PASSWORD`, эта учётная запись получает `MUST_CHANGE_PASSWORD` при каждом вызове, пока пароль не будет изменён.

## Задания

Задание, завершившееся ошибкой, сообщает причину в самом задании, а не в ошибке HTTP. Прочитайте `error.code` и `error.message` из `GET /api/v1/jobs/{jobId}`. См. [Отслеживание прогресса](/ru/api/rest#progress-tracking).

Неудачное задание сохраняет `error.code` только тогда, когда сбой является ошибкой входных данных или неисправностью сервера. Остальные сбои содержат только сообщение.

| `code` | Значение | Что делать |
|--------|---------|------------|
| `CANCELED` | Задание отменено пользователем. Это не статус HTTP. События прогресса несут `phase: failed` с этим кодом. | Считайте это отменой пользователем. Не повторяйте его автоматически. |
| `INPUT_MISSING` | Входные данные были удалены до запуска задания. | Загрузите файл снова. |
| `ENGINE_UNAVAILABLE` | Нужный движок не удалось запустить на сервере. | Повторите после того, как администратор исправит установку. |
| `JOB_STALLED` | Клиентам не возвращается; помечает отчёт сервера об ошибке. Обработчик потерял блокировку задания больше раз, чем допускает очередь, обычно из-за перезапуска сервера или нехватки памяти или ЦП. Задание завершается сообщением о том, что оно было прервано. | Повторите. Если это повторяется, дайте серверу больше памяти или уменьшите `CONCURRENT_JOBS`. |

## Аутентификация и MFA

| `code` | Статус | Значение | Что делать |
|--------|--------|---------|------------|
| `MFA_ENROLLMENT_REQUIRED` | 403 | Политика MFA требует регистрации, а этот экземпляр не может зарегистрировать пользователя (нет корпоративной лицензии). Экземпляры с лицензией вместо этого возвращают 200 с `requiresMfaEnrollment: true` и проводят пользователя через регистрацию. | Не повторяйте. Администратор должен изменить политику или воспользоваться автономным CLI восстановления. |
| `MFA_POLICY_UNAVAILABLE` | 503 | Серверу не удалось прочитать политику MFA во время входа. | Вскоре повторите вход. |
| `INVALID_CODE` | 401 | Код TOTP или код восстановления неверен. | Попросите у пользователя новый код и повторите. Повторные сбои заканчиваются `MFA_ATTEMPTS_EXHAUSTED`. |
| `MFA_ATTEMPTS_EXHAUSTED` | 401 | Слишком много неверных кодов. Запрос подтверждения сброшен. | Начните вход заново, чтобы получить новый запрос подтверждения. |
| `MFA_EXPIRED` | 401 | Запрос подтверждения MFA или регистрации истёк или не совпадает. | Начните вход заново. |
| `MFA_NOT_CONFIGURED` | 401 | У учётной записи нет секрета TOTP, поэтому код проверить нельзя. | Зарегистрируйте MFA, прежде чем входить с кодом. |
| `MFA_ALREADY_ENABLED` | 409 | MFA уже активна для учётной записи. | Не регистрируйте её снова. |
| `NO_PENDING_ENROLLMENT` | 400 | Подтверждение регистрации пришло без ожидающей регистрации. | Сначала вызовите эндпоинт регистрации. |
| `MFA_NOT_ENABLED` | 400 | Для действия нужно, чтобы MFA была включена, а для этого пользователя она выключена. | Пропустите действие или сначала включите MFA. |
| `MFA_DECRYPTION_FAILED` | 500 | Сохранённый секрет TOTP невозможно расшифровать. | Действие оператора. Обычно это означает, что ключ шифрования изменился. Проверьте `DATA_ENCRYPTION_KEY` и `DATA_ENCRYPTION_KEY_PREVIOUS`. |
| `DECRYPTION_FAILED` | 500 | Сохранённое значение (настройку, заголовок аутентификации вебхука или секрет TOTP) невозможно расшифровать. | Действие оператора, как выше. Не повторяйте. |
| `IDLE_TIMEOUT` | 401 | Сессия истекла после периода бездействия. | Войдите снова. |
| `INVALID_PASSWORD` | 401 | Текущий пароль неверен при смене пароля. | Попросите у пользователя текущий пароль. |
| `PASSWORD_CHANGED` | 409 | Пароль был изменён в другой сессии или сброшен администратором, пока выполнялся этот запрос. | Войдите снова. |
| `OIDC_NO_PASSWORD` | 400 | Смена или сброс пароля запрошены для учётной записи, созданной через SSO. | Направьте пользователя к поставщику удостоверений. |

## OIDC

Ошибки OIDC при входе не возвращают тело JSON. Маршрут входа перенаправляет на страницу входа с общей причиной, а журнал аудита записывает код. Маршрут выхода по-прежнему завершает локальную сессию, когда поставщик удостоверений недоступен.

| `code` | Статус | Значение | Что делать |
|--------|--------|---------|------------|
| `OIDC_ISSUER_SCHEME_MISMATCH` | Нет (перенаправление) | URL издателя: `http`, но `EXTERNAL_URL` равно `https`, поэтому клиент отказывается от обнаружения. | Администратор: обслуживайте издателя по `https` или запустите экземпляр по `http`. |
| `OIDC_DISCOVERY_TIMEOUT` | Нет (перенаправление) | Время ожидания обнаружения издателя истекло. | Проверьте, что сервер может связаться с издателем, затем повторите. |
| `OIDC_DISCOVERY_FAILED` | Нет (перенаправление) | Обнаружение не удалось по другой причине. | Проверьте URL издателя и исходящий доступ сервера. |
| `OIDC_END_SESSION_INVALID` | Нет (выход продолжается) | `end_session_endpoint` поставщика удостоверений не является допустимым URL. Локальная сессия всё равно очищается. | Администратор: исправьте метаданные поставщика. |
| `OIDC_END_SESSION_SCHEME` | Нет (выход продолжается) | `end_session_endpoint` использует схему, которую сервер не разрешает. Локальная сессия всё равно очищается. | Администратор: исправьте метаданные поставщика. |

## SAML

Ошибки SAML не задают `code`. Неудачное утверждение перенаправляет на страницу входа с `saml_auth_failed`, а событие аудита `SAML_LOGIN_FAILED` записывает причину.

## SCIM

Маршруты SCIM отвечают конвертом ошибки RFC 7644 (`schemas`, `detail`, `status` и иногда `scimType`). Они не задают `code`. Ветвите логику по статусу HTTP.

## Команды, роли и пользователи

Повторяющиеся названия команд или ролей возвращают общий `CONFLICT`, а отсутствующая команда или роль возвращает `NOT_FOUND`.

| `code` | Статус | Значение | Что делать |
|--------|--------|---------|------------|
| `ESCALATION_DENIED` | 403 | Роль вызывающего не позволяет это изменение. Цель стоит выше полномочий вызывающего, роль встроенная, или запрос выдаёт разрешения, которых у вызывающего нет. | Не повторяйте. Обратитесь к пользователю с большими полномочиями. |
| `UNKNOWN_ROLE` | 400 | Идентификатор роли не соответствует существующей роли. | Исправьте идентификатор роли. Выведите список ролей, чтобы найти его. |
| `UNKNOWN_TEAM` | 400 | Идентификатор команды не соответствует существующей команде. | Исправьте идентификатор команды. |
| `SELF_DEMOTE` | 400 | Администратор попытался снять с себя роль администратора. | Пусть изменение внесёт другой администратор. |
| `SELF_DELETE` | 400 | Администратор попытался удалить собственную учётную запись. | Пусть её удалит другой администратор. |
| `LAST_ADMIN` | 400 на маршрутах пользователей, 409 на маршрутах очистки GDPR | Изменение не оставит ни одного администратора или очистит команду, в которой состоят все администраторы. | Сначала сделайте администратором другого пользователя. |
| `USER_LIMIT_REACHED` | 403 | Экземпляр достиг предела `MAX_USERS`. | Удалите пользователя или увеличьте `MAX_USERS`. |

## Функции и пакеты ИИ

Инструменты, пакетные запуски и конвейеры, которым нужен необязательный пакет ИИ, используют эти коды.

| `code` | Статус | Значение | Что делать |
|--------|--------|---------|------------|
| `FEATURE_NOT_INSTALLED` | 501 или 400 из режима лиц в Smart Crop | Инструменту или одному шагу конвейера или пакетного запуска нужен пакет, который не установлен. Тело включает `feature` (идентификатор пакета) и `featureName`. | Установите пакет в настройках, затем повторите. |
| `FEATURE_CPU_UNSUPPORTED` | 409 | Установка или автономный импорт отклонены, потому что библиотекам x86-64 этого пакета нужен AVX, а ЦП этого сервера его не поддерживает. Ничего не было скачано или установлено. Тело включает `feature` (идентификатор пакета) и `reason` (`cpu-no-avx`). `GET /api/v1/features` сообщает об этом же пакете с `compatibility: "incompatible"` и `compatibilityReason: "cpu-no-avx"`. | Запустите SnapOtter на ЦП с AVX или на arm64. Другие пакеты по-прежнему устанавливаются. |
| `FEATURE_INCOMPATIBLE` | 501 или 400, когда Fast OCR получает язык, который не может прочитать | Установленная функция не поддерживает запрошенное качество или язык. | Измените настройку или установите пакет, который это поддерживает. |
| `ENGINE_UNAVAILABLE` | 503 | Нужный движок не удалось запустить, или среда выполнения OCR была удалена после проверки запроса. | Повторите после того, как администратор исправит или переустановит функцию. |
| `BROWSER_NOT_AVAILABLE` | 503 | Chromium не установлен, поэтому HTML to image не может работать. | Попросите администратора установить браузер. |
| `BROWSER_CRASHED` | 503 | Браузер для снимков экрана аварийно завершился при отрисовке. | Повторите запрос. |

## Инструменты

| `code` | Статус | Значение | Что делать |
|--------|--------|---------|------------|
| `INPUT_MISSING` | 410 | Загруженные входные данные были удалены до запуска задания. | Загрузите файл снова и отправьте задание. |
| `ANALYSIS_EXPIRED` | 410 | Анализ фото на паспорт истёк до создания. | Проанализируйте фото снова, затем создайте. |
| `BACKGROUND_REMOVAL_EXPIRED` | 410 | Результат удаления фона истёк до следующего шага. | Удалите фон снова. |
| `NOT_ANIMATED` | 400 | Remove GIF Background получил статичное изображение. | Для статичных изображений используйте Remove Background. |
| `TOO_MANY_FRAMES` | 400 | В анимации больше кадров, чем разрешает сервер (`GIF_BG_MAX_FRAMES`). | Отправьте более короткую анимацию или попросите администратора увеличить предел. |
| `TOO_MANY_PIXELS` | 400 | Холст анимации, умноженный на число кадров, превышает предел сервера: 268 402 689 пикселей (16383 x 16383) для Remove GIF Background или предел нагрузки GIF для других анимированных инструментов. | Отправьте меньше кадров или меньшую анимацию. |
| `IMAGE_TOO_LARGE` | 400 | В изображении больше пикселей, чем принимает декодер. | Отправьте изображение поменьше. |
| `RESULT_TOO_LARGE` | 400 | Настройки дадут изображение больше, чем допускает кодировщик или предел пикселей. | Используйте изображение поменьше или настройки, дающие меньший результат. |
| `DOCUMENT_UNREADABLE` | 400 | LibreOffice или pandoc не смогли открыть документ. Он может быть повреждён, защищён паролем или не соответствовать формату, указанному в расширении. | Проверьте, что файл открывается в офисном приложении, затем отправьте его снова. |
| `PDF_DAMAGED` | 400 | Движок PDF обнаружил нарушенную структуру документа. | Пропустите файл через Repair PDF, затем повторите. |
| `PDF_PASSWORD_PROTECTED` | 400 | PDF зашифрован, и этот инструмент не может его открыть. | Сначала разблокируйте его через Unlock PDF. |
| `NO_AUDIO_TRACK` | 400 | В файле нет аудиопотока, который мог бы использовать аудиоинструмент. | Отправьте файл со звуком. |
| `MEDIA_UNDECODABLE` | 400 | ffmpeg не смог прочитать аудио или видео: он не нашёл пакетов, параметров кодека, атома `moov` или данных, которые можно разобрать. | Проверьте, что файл воспроизводится в медиаплеере, или экспортируйте его заново, затем повторите. |
| `PAGE_OUT_OF_RANGE` | 400 | Диапазон страниц указывает страницу, которой нет в PDF. | Проверьте число страниц и отправьте диапазон внутри него. |
| `INVALID_PAGE_RANGE` | 400 | Диапазон страниц имеет недопустимый синтаксис. | Используйте номера страниц вида `1-3,5`. |
| `CANNOT_REMOVE_ALL_PAGES` | 400 | Remove Pages попросили удалить все страницы. | Оставьте хотя бы одну страницу. |
| `NESTING_TOO_DEEP` | 400 | Вложенность JSON или XML превышает 100 уровней. | Упростите структуру документа, затем преобразуйте его. |
| `IMAGE_UNDECODABLE` | 400 | Изображение не удаётся декодировать, или не удаётся прочитать его размеры. Файл может быть повреждён или использовать кодировку, которую декодер не поддерживает. | Экспортируйте изображение заново из другого приложения или сначала преобразуйте его в PNG или JPEG. |
| `INVALID_SETTINGS` | 400 | Настройка выходит за допустимый диапазон или не подходит этому файлу: обрезка за пределами изображения, изменение размера до нуля, кадр GIF, которого нет в анимации, несуществующая спецификация фото на паспорт. Текст `error` называет настройку. | Исправьте настройку, названную в `error`, затем повторите. |
| `CHART_DATA_INVALID` | 400 | Chart Maker не смог прочитать данные диаграммы из файла: CSV или JSON не разбирается, в нём нет числового столбца, больше 100 строк или есть отрицательное значение. Текст `error` говорит, что именно. | Отправьте CSV или JSON не более чем со 100 строками, в каждой метка и число, равное нулю или больше. |
| `NO_FACE_DETECTED` | 400 | Passport Photo не нашёл лицо на изображении. | Отправьте чёткое фото анфас при хорошем освещении. |
| `TARGET_SIZE_UNREACHABLE` | 400 | Сжатие или ограничение размера фото на паспорт не может уместить файл в запрошенный размер, даже после уменьшения. | Запросите больший целевой размер или сначала обрежьте изображение. |
| `TOO_MANY_PAGES` | 400 | OCR попросили обработать больше страниц, чем он обрабатывает за одно задание. | Выберите меньше страниц с помощью диапазона страниц. |
| `METADATA_DAMAGED` | 400 | Edit Metadata обнаружил, что существующие данные EXIF изображения повреждены, поэтому не может безопасно их переписать. | Сначала удалите метаданные через Remove Image Metadata, затем редактируйте. |
| `REMOTE_RESOURCES_DISABLED` | 400 | HTML или Markdown to PDF обнаружил ссылку на изображение, таблицу стилей или шрифт в сети, которые сервер не загружает. | Встройте ресурс в файл (например, как URI `data:`), затем повторите. |

## Файлы

| `code` | Статус | Значение | Что делать |
|--------|--------|---------|------------|
| `STORAGE_QUOTA_EXCEEDED` | 413 | Сохранение в Files превысит квоту хранилища пользователя. | Удалите файлы или попросите администратора выделить больше места. |
| `INVALID_STORED_NAME` | 400 | Сервер отклонил сохранённое имя файла. | Загрузите файл снова. |

## Конвейеры и пакетная обработка

Запросы конвейеров и пакетной обработки возвращают описанные выше коды функций для каждого шага, которому нужен пакет. Идентификатор задания, который уже используется, возвращает `CONFLICT` со статусом 409. Отправьте новый идентификатор задания.

## Настройки

| `code` | Статус | Значение | Что делать |
|--------|--------|---------|------------|
| `UNKNOWN_SETTING` | 400 | Ключ не является известной настройкой. | Проверьте имя ключа. |
| `READONLY_SETTING` | 400 | Настройку нельзя изменить через API. | Измените её через окружение или интерфейс администратора. |
| `DEPENDENCY_VALIDATION_FAILED` | 400 | Новое значение конфликтует с другими настройками. Тело называет настройку в `setting` и перечисляет проблемы в `validationErrors`. | Исправьте перечисленные настройки, затем повторите. |
| `SETTING_DECRYPTION_FAILED` | 500 | Сохранённую настройку невозможно расшифровать. | Действие оператора, как для `DECRYPTION_FAILED`. |

Для `VALIDATION_ERROR` у настройки `details` содержит проблемы схемы.

## Enterprise

| `code` | Статус | Значение | Что делать |
|--------|--------|---------|------------|
| `FEATURE_NOT_LICENSED` | 403 | Настройке или политике нужна корпоративная лицензия, например принудительному SSO или политике MFA. | Используйте экземпляр с лицензией или оставьте настройку выключенной. |
| `IP_NOT_ALLOWED` | 403 | IP-адреса запроса нет в списке разрешённых. | Подключитесь из разрешённой сети. |
| `INVALID_CIDR` | 400 | Запись списка разрешённых не является допустимым CIDR. Сообщение перечисляет неверные записи. | Исправьте записи и сохраните снова. |
| `SELF_LOCKOUT` | 400 | Сохранение списка разрешённых заблокирует текущий IP вызывающего. | Сначала добавьте в список свой текущий IP. |

Маршруты очистки GDPR возвращают простой `CONFLICT` со статусом 409, когда пользователь или команда находятся под судебным удержанием.

## Коды, которые клиенты не получают

Эти коды существуют в исходном коде сервера для журналов, телеметрии или собственных ошибок Fastify. Клиент не получает их в теле ответа или строке задания, поэтому не пишите клиентскую логику на их основе.

| `code` | Куда попадает |
|--------|---------------|
| `ALERT_DECRYPTION_FAILED` | Передаётся в отслеживание ошибок оценщиком оповещений. Заголовок аутентификации вебхука оповещения невозможно расшифровать. |
| `SIEM_DECRYPTION_FAILED` | Передаётся в отслеживание ошибок пересылкой SIEM. Заголовок аутентификации SIEM невозможно расшифровать. |
| `WEBHOOK_DECRYPTION_FAILED` | Передаётся в отслеживание ошибок. Запрос, столкнувшийся с тем же сбоем, отвечает `DECRYPTION_FAILED`. |
| `STAGED_DISCARD_FAILED` | Передаётся в отслеживание ошибок, когда промежуточную загрузку не удаётся удалить. |
| `USERNAME_RACE_EXHAUSTED` | Возникает, когда автосоздание SSO проигрывает гонку за имя пользователя при каждой повторной попытке. Вместо этого страница входа показывает ошибку. |
| `ERR_OUT_OF_RANGE` | Выбрасывается читателем объектного хранилища при недопустимом диапазоне байтов. |
| `ETIMEDOUT` | Задаётся в ошибке тайм-аута экспорта GDPR. Экспорт завершается неудачей, и его можно запросить снова. |
| `FST_REQ_FILE_TOO_LARGE` | Код Fastify для загрузки сверх предела. Клиенты получают 413 с `PAYLOAD_TOO_LARGE` или собственное сообщение 413 маршрута. |
| `TARGET_SIZE_EXCEEDED` | Выбрасывается, когда сжатие до целевого размера не достигает цели. У ошибки нет статуса или кода, поэтому клиенты получают общий сбой. |
| `OCR_CACHE_PERMISSIONS` | Передаётся в отслеживание ошибок как эксплуатационная неисправность, когда том данных ИИ оставляет кэш среды выполнения OCR доступным для записи всем. Задание установки завершается сообщением, называющим проблему с хранилищем. |
| `OCR_RUNTIME_UNREACHABLE` | Передаётся в отслеживание ошибок как эксплуатационная неисправность, когда сервер так и не связался с huggingface.co для загрузки среды выполнения OCR. Задание установки завершается сообщением о сетевом доступе, `HTTPS_PROXY` и автономном импорте. |
