# Troubleshooting Симптом → причина → действие. Только подтверждённое поведение стендов. ## 401 «Ключ доступа не передан или неверен» - Забыт заголовок `X-API-Key` / ключ не совпадает со `WORDPDF_API_KEY` сервера. - Prod-like стенд не поднимается без `.env` — это fail-closed (`${WORDPDF_API_KEY:?}`), не баг. - Запрос идёт через точечный сегмент (`/actuator/../api/...`) — открытые префиксы с `..`/`%2e` ключем не обходятся, так и задумано. - Фронт: экран ключа не появляется, хотя сервер его требует? Проверьте, что `probeApiKey()` дошёл до сервера (network-вкладка); ключ из localStorage стирается при 401. ## 422 «Конвертация отменена: … найдены диаграммы/SmartArt/OLE-объекты» Не ошибка — сработал включённый error-флаг запроса. Снимите `errorOnCharts`/ `errorOnSmartArt`/`errorOnOle` (по умолчанию выключены). На `.doc` флаги не срабатывают в принципе (плейсхолдеры — растры). ## 503 Очередь конвертации (16 мест) полна: воркер один, все конвертации сериализованы. Повторите позже. Систематически — увеличивайте время ответа вниз (документы поменьше) или масштабируйте количество экземпляров за балансировщиком (каждый со своей очередью). ## 504 Конвертация дольше `wordpdf.convert-timeout` (2m). Уменьшите документ (много больших растров/диаграмм) или поднимите таймаут серверу. Учтите: отменённая конвертация дожигается, следующий запрос ждёт её в очереди. ## 413 Тело больше контейнерного потолка multipart (100 МБ) или nginx `client_max_body_size 100m` — обе границы стоят 100 МБ. Логический лимит входа (`wordpdf.max-mb`, дефолт 5 МБ) отсекает раньше и даёт 400, так что 413 — это когда серверный лимит поднят выше 100 МБ бессмысленно либо запрос идёт мимо ожидаемого пути. Файл реально меньше, но 413? Проверьте, не режет ли промежуточный прокси. ## В PDF напечатано «...TO HIDE THESE MESSAGES...» В classpath нет SLF4J-провайдера — docx4j пишет предупреждения прямо в PDF. Для библиотеки: оставить `slf4j-simple` (в транзитивах `wordpdf-core`) или принести свой провайдер. Для app: `slf4j-simple` исключён в пользу logback — если логическая конфигурация app сломана и SLF4J не инициализирован, верните провайдер. ## Картинки диаграмм «мыльные» (ресемпл) Нарушен контракт префикса media-частей `/word/media/chart-*`: по нему `ChartImageHandler` отключает пересжатие PNG в FOP. Если части переименованы ручной правкой — верните префикс (`DrawingPreRenderer.CHART_MEDIA_URI_PREFIX`). ## Вместо знаков — `#` или пустые боксы - `#` — глифа нет ни в шрифте ранa, ни в fallback, и не сработала резка по покрытию (для docx-пута это регрессия — заведите issue с документом). - Пустой бокс `.notdef` для U+2188/U+218A — известное ограничение OFL-бандла, не чинится. - «Битый»/подменённый шрифт в целом — проверьте алиасы (`Calibri→Carlito` и т.д., [Шрифты](../architecture/fonts.md)): подмена метрически совместима и ожидаема. ## Стенд крутит старый код после пересборки podman-compose пересобрал образ, но контейнеры остались на старом — перезапустите с `--force-recreate` ([Стенды](stack.md)). ## `.doc` не конвертируется (400) Проверьте сигнатуру: `D0 CF 11 E0 A1 B1 1A E1`. Word 6–95 и зашифрованные (Office 95 password) документы мостом не поддерживаются → 400/`ValidationException`. Расширение `.doc` при zip-содержимом (переименованный docx) маршрутизируется по байтам — это не ошибка.