Ошибки

Здесь форма ответов API и коды, которые может вернуть любой эндпоинт, а разбор частых проблем и полная таблица кодов по эндпоинтам — на странице «Ошибки и частые проблемы» и в кодах ошибок.

Во всех примерах API — https://onpress.pro/api/v2, SITE — id сайта (SITE_ID), OP_TOKEN — токен op_XXXX. Полный перечень эндпоинтов — в справочнике API.

Успешный ответ

Успешный ответ — объект с "success": true и полями эндпоинта; на адресе /site/{siteId}/… в нём есть site_id. Если запрос выполнен, но что-то в нём стоит поправить, в ответе появляется массив warnings с пояснениями на английском. Например, публикация черновика проходит, а ответ напоминает, что по адресу страницу пока не видно. Свои ключи из свойств страницы ответ публикации перечисляет не в warnings, а в отдельном поле data_keys.

curl -s -X POST "$API/site/$SITE/pages/markdown" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"markdown": "---\nname: Проба\nstatus: draft\n---\n\nТекст."}'

{
  "success": true,
  "site_id": "x9HTLHECq",
  "updated": false,
  "id": 6446,
  "…": "…",
  "warnings": ["page is not published (status \"draft\"), the address does not serve it"]
}

Поле	Тип	Описание
`success`	boolean	`true`
`site_id`	строка	id сайта, если он назван в пути
`warnings`	массив строк	предупреждения: проигнорированное поле, почищенный якорь, неопубликованная страница; есть не всегда

Отказ эндпоинта

Если запрос дошёл до эндпоинта и тот отказал, ответ — объект с "success": false, машинным кодом в error, пояснением в message и полями конкретного отказа рядом. Например, запрос несуществующего поля настроек:

curl -s "$API/site/$SITE/data/settings/description" \
  -H "Authorization: Bearer $OP_TOKEN"

{
  "success": false,
  "error": "unknown_settings_field",
  "message": "there is no settings field \"description\"; the fields are: name, icon, closed, front_page, languages, metrika, ga, gsc, webmaster. The site description is not a field of v2",
  "fields": ["name", "icon", "closed", "front_page", "languages", "metrika", "ga", "gsc", "webmaster"]
}

Поле	Тип	Описание
`success`	boolean	`false`
`error`	строка	машинный код отказа
`message`	строка	пояснение на английском, текст может уточняться
другие поля	любой	подробности отказа: допустимые значения, имя поля, версия страницы

Отказ до эндпоинта

Отказы при проверке токена, выбора сайта и лимита, неразборчивое тело и несуществующий маршрут приходят в другой форме: код в поле code, статус — в data.status. Например, запрос к несуществующему сайту:

curl -s "$API/site/AAAAAAAAA/menus" \
  -H "Authorization: Bearer $OP_TOKEN"

{ "code": "site_not_found", "message": "there is no site AAAAAAAAA you can reach with these credentials", "data": { "status": 404 } }

Ветвитесь по error или code и HTTP-статусу, а не по тексту message.

Общие коды

Эти коды может вернуть любой эндпоинт; коды конкретных эндпоинтов — на их страницах справочника и в кодах ошибок.

Код	Статус	Когда	Что делать
`missing_token`	401	нет заголовка с токеном	добавить `Authorization: Bearer $OP_TOKEN`
`invalid_token`	401	токен не той формы, неизвестен или отозван	взять действующий токен
`too_many_auth_failures`	429	больше 20 неудачных попыток с токеном за минуту с одного адреса	подождать `Retry-After` секунд, исправить токен
`cross_origin`	403	запрос с кукой сессии пришёл не с адреса консоли	отправить запрос с токеном
`site_not_found`	404	сайта нет или вы не его администратор	проверить `siteId`
`insufficient_role`	403	вы участник сайта, но не администратор	получить права администратора
`too_many_requests`	429	больше 120 запросов в минуту	подождать `Retry-After` секунд и повторить
`invalid_json`	400	тело не разбирается как JSON	проверить тело и `Content-Type: application/json`
`body_too_large`	413	тело больше 10 МБ	разбить запрос на части
`not_found`	404	нет такого маршрута	проверить метод и путь по справочнику
`method_not_allowed`	405	`GET` на эндпоинт входа, который работает только с `POST`	отправить `POST`
`dry_run_not_supported`	400	`dry_run` у эндпоинта, у которого нет пробного прогона	убрать `dry_run`; ничего не записано
`gone`	410	эндпоинт снят	перейти на адрес из `message`
`wrong_realm`	409	запись пришла не на рабочий адрес API; ничего не записано	отправить тот же запрос на `https://onpress.pro/api/v2`
`internal_error`, `auth_error`	500	сбой сервиса	повторить позже; не проходит — написать в поддержку
`db_error`	500	база отказала в записи, код драйвера в `db_code`	повторить позже; не проходит — написать в поддержку
`internal_unavailable`	502	исполнитель на стороне сайта не ответил	повторить позже

Повтор после 429

Ответ 429 несёт заголовок Retry-After — через сколько секунд освободится место в окне. Подождите столько секунд и повторите тот же запрос; запрос с отказом 429 ничего не записал. Например, чтобы увидеть заголовок:

curl -s -D - -o /dev/null "$API/site/$SITE/pages" \
  -H "Authorization: Bearer $OP_TOKEN"

HTTP/2 429
retry-after: 15
x-ratelimit-limit: 120
x-ratelimit-remaining: 0
x-ratelimit-reset: 1793135747

Лимиты и заголовки X-RateLimit-* — в разделе «Авторизация».