Files
java-word-pdf/docs/api/errors.md
T
Pjandro b3511f8b74 docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
2026-11-22 21:39:08 +03:00

3.6 KiB

Коды ошибок

Ошибки — JSON вида {"error": "..."}.

Полная таблица

Код Смысл
200 PDF в теле ответа
400 некорректный вход (пустой / расширение не .docx/.doc / содержимое не zip и не CFB / зашифрованный .doc / больше лимита размера (maxMb или wordpdf.max-mb) / больше лимита страниц (maxPages или wordpdf.max-pages) / maxMb≤0 / maxPages≤0), отсутствующая часть file, некорректное значение error-флага
401 нет или неверен X-API-Key
404 неизвестный путь (в т.ч. /v3/api-docs при выключенном springdoc)
405 не-POST
413 тело запроса больше контейнерного лимита multipart (100 МБ; авторитетный лимит входа — wordpdf.max-mb, он даёт 400 раньше)
415 не-multipart тело
422 сработал error-флаг: в документе найдены диаграммы / SmartArt / OLE-объекты
500 ошибка ядра/рендера
503 очередь конвертации (16 мест) переполнена — повторить позже
504 конвертация дольше wordpdf.convert-timeout (по умолчанию 2m)

Фиксированные тексты

Тексты ниже — контракт с фронтендом, они не меняются:

Код Тело
401 {"error":"Ключ доступа не передан или неверен (заголовок X-API-Key)"}
404 {"error":"Не найдено"}
405 {"error":"Метод не поддерживается"}
415 {"error":"Неподдерживаемый тип содержимого"}
422 (диаграммы) {"error":"Конвертация отменена: в документе найдены диаграммы"}
422 (SmartArt) {"error":"Конвертация отменена: в документе найден SmartArt"}
422 (OLE) {"error":"Конвертация отменена: в документе найдены OLE-объекты"}
500 {"error":"Не удалось конвертировать документ"}

Другие 400-тексты параметризованы, например: Файл не передан (multipart-поле «file» обязательно), Поддерживаются только .docx и .doc: <имя>, Файл больше <N> МБ: …, Некорректное значение параметра «<имя>».

!!! info "500 — деталь только в лог" Сообщения ядра (ConversionException и др.) логируются на сервере, наружу всегда уходит фиксированный текст — внутренние детали не текут клиенту.

Исключение → обработчик (для отладки)

HTTP Источник
400 ValidationException, BadRequestException, MethodArgumentTypeMismatchException, MissingServletRequestPartException
401 ApiKeyFilter (пишет ответ сам, до диспетчера)
404 / 405 / 415 NoResourceFoundException / HttpRequestMethodNotSupportedException / HttpMediaTypeNotSupportedException
413 MaxUploadSizeExceededException
422 DrawingRejectedException
500 ConversionFailedException
503 ConversionRejectedException
504 ConversionTimeoutException