Ошибки и частые проблемы
Во всех примерах API — https://onpress.pro/api/v2, SITE — id сайта (SITE_ID), OP_TOKEN — токен op_XXXX. Полный перечень эндпоинтов — в справочнике API.
Как читать ошибку
Ошибка эндпоинта:
{ "success": false, "error": "parent_not_found", "message": "parent page \"net-takogo\" from path \"/net-takogo/x/\" does not exist in language en; publish the parent page first", "segment": "net-takogo" }
Ошибка до эндпоинта (токен, выбор сайта, тело, маршрут):
{ "code": "missing_token", "message": "an API token is required: Authorization: Bearer <token> or X-OnPress-Key header", "data": { "status": 401 } }
Ветвитесь по коду (error или code) и HTTP-статусу. message — пояснение на английском, в нем обычно сказано, что делать; дополнительные поля несут подробности (languages, candidates, allowed, errors). Полная таблица кодов — коды ошибок.
Предупреждения — не ошибки, но читать их обязательно. Успешный ответ несет warnings: проигнорированный template, сменившийся слаг, неопубликованный родитель, пропущенный вложенный фрейм. Все, что API сделал не так, как вы просили, приходит сюда, а не отказом.
Частые проблемы
Опубликованная страница отвечает 404
Почти всегда у страницы нет фрейма: на сайте v2 страницу выводит только ее фрейм. Проверьте GET /pages/{ref} → page.frame; null — поставьте фрейм (PATCH /pages/{ref} с frame). Другие причины: статус не publish или неопубликован кто-то из родителей (visible: false в ответе публикации); фрейма уже нет; адрес другой — возьмите его из link (у языка не по умолчанию есть префикс /en/…).
Правка не видна на сайте
Проверяйте запросом без кук: запрос с куками входа видит свежую страницу, а посетитель — копию из кэша. API сбрасывает кэш зависимых страниц сам — и когда блок стоит во фрейме страницы, и когда он вставлен прямо в тело через вызов frame/… или onpress/repeat; какие страницы API обновил, показывают поля ответа записи rebaked.pages и rebaked.cache.pages. Если правили мимо API, сбросьте кэш адреса — POST /cache/flush {"urls": ["/адрес/"]}. Если у страницы статическая копия, а правили что-то мимо API, — POST /frames/rebake.
Страница задвоилась
Публикация без id ищет существующую страницу по слагу под тем же родителем. Поменяли url на другого родителя — API не нашел страницу под новым родителем и создал вторую. Удалите дубль (DELETE /pages/{id}?force=true) и публикуйте с id в свойствах. Так же дубль появляется при ошибке в слаге или другом lang.
Адрес получился не тот
API берет слаг из slug, а не из последнего сегмента url, а без slug собирает его из заголовка. Пишите slug и url согласованно. Если слаг занят в том же языке под тем же родителем, API добавит суффикс -2 — смотрите slug_changed в ответе.
Меню пустое
Смотрите GET /data/menu.<область>?lang=<язык>: meta.menu_id: 0 — в области на этом языке нет меню (PUT /data/menus.location); meta.invalid_items больше нуля — пункты ведут на удаленные или черновые страницы; same_name_dataset — шапка сайта берет пункты из набора с тем же коротким именем. Если GET /data/menus показывает меню в области, а на странице пусто, сравните theme в ответе с темой сайта.
Поле данных не подставилось
Двойные кавычки вокруг атрибута data-op-bind обрывают его — берите атрибут в одинарные. Поле данных без значения (page.parent_title у страницы верхнего уровня) или с ошибкой в имени — оно в bake.response.unresolved ответа записи фрейма. item.* работает только внутри onpress/repeat.
Повторитель пуст
POST /data/resolve с теми же source, match, page, lang покажет, что он получает. Частые причины: контекстный источник (pages.children, breadcrumbs) без страницы; match по полю, которого нет у элементов; повторитель сравнивает значения строками ("3" равно 3, но "3 " — нет); вариант набора на языке страницы пуст, а общего набора нет.
Перевод не связался
422 translation_link_failed с reason: нет lang (lang_required), язык совпадает с оригиналом (same_language), оригинала нет (origin_not_found), у оригинала нет языка (origin_has_no_language — почините POST /pages/language). 409 lang_mismatch — в свойствах перевода остался id оригинала; выгружайте с ?as=translation_source.
401 на каждом запросе
missing_token — заголовок не дошел (проверьте Authorization: Bearer $OP_TOKEN и что переменная задана). invalid_token — токен перевыпустили или отозвали, или вы скопировали его не целиком (нужны op_ и 64 символа). После 20 неудачных попыток в минуту с адреса — 429 too_many_auth_failures: подождите Retry-After.
403 insufficient_role или 404 site_not_found
Вы не администратор этого сайта. Чужой и несуществующий сайт отвечают одинаково — 404 site_not_found, а участник сайта без прав администратора получает 403 insufficient_role.
429 too_many_requests
Больше 120 запросов в минуту. Счетчик токена и счетчик сессии консоли раздельные: агент, упершийся в лимит, консоль не блокирует. Ждите Retry-After секунд; в каждом ответе есть X-RateLimit-Remaining. Массовые операции (заливка десятков картинок, страниц) делайте с паузами.
502 internal_unavailable
Исполнитель на стороне сайта не ответил. Это не ошибка вашего запроса: то, что API уже сохранил (фрейм, данные), остается на месте — повторите вызов позже. Если отказ повторяется на одном сайте, значит на сайте нет исполнителя или сайт не отвечает.
Страница на многоязычном сайте уводит сама на себя
У страницы нет языка. POST /pages/language {"missing": true} проставит язык по умолчанию всем таким страницам.
Как искать причину самому
- Прочитайте сущность обратно:
GET /pages/{ref},GET /frames/{ref},GET /data/{name}— API отдает то, что лежит на самом деле. - Посмотрите страницу без кук и найдите в исходном коде комментарии с пометкой
op/…: …— каждый блок, которому нечего вывести, оставляет пояснение. - Проверьте повторители через
POST /data/resolve. - Сравните
printed.howиstaticс ожиданием:on_requestтам, где ждали статику, — во фрейме есть что-то зависящее от страницы.