Ошибки
Здесь формы ответа и общие коды ошибок API. Как исправлять частые проблемы — в гайде; специальные коды описывает каждый эндпоинт справочника.
Во всех примерах API — https://onpress.pro/api/v2, SITE — id сайта (SITE_ID), OP_TOKEN — токен op_XXXX. Полный перечень эндпоинтов — в справочнике API.
Успешный ответ
Успешный ответ — объект с "success": true и полями эндпоинта; на адресе /site/{siteId}/… ответ называет сайт заголовком X-OnPress-Site-Id, а многие эндпоинты — еще и полем 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",
"fields": ["name", "icon", "closed", "front_page", "languages", "metrika", "ga", "gsc", "webmaster"]
}
| Поле | Тип | Описание |
|---|---|---|
success | boolean | false |
error | строка | машинный код отказа |
message | строка | пояснение на английском, текст может уточняться |
| другие поля | любой | подробности отказа: допустимые значения, имя поля, версия страницы |
Отказ до эндпоинта
Отказы при проверке токена, выбора сайта и лимита, неразборчивое тело и несуществующий маршрут приходят в другой форме: код в поле code, статус — в data.status. Например, запрос к несуществующему сайту:
curl -s "$API/site/AAAAAAAAA/data/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.
Общие коды
Общая авторизация и обработка запросов возвращают эти коды. Специальные коды и действия описывает профильная операция справочника.
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
operation_failed | 502 | Профильная операция системных данных сообщила о неудаче без собственного кода; детали в result. | Проверьте result и повторите действие после устранения причины. |
source_read_not_supported | 405 | GET у имени, предназначенного только для записи. | Используйте методы из write.methods в каталоге системных данных. |
source_auth_required | 403 | Для профильной операции не определен авторизованный администратор сайта. | Проверьте токен и доступ к выбранному сайту. |
wrong_method_for_source | 405 | Метод не поддерживается этим именем системных данных. | Используйте метод из справочника сущности или каталога. |
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 | API не может разобрать тело как 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 — через сколько секунд освободится место в окне. Подождите столько секунд и повторите тот же запрос; API не исполнил операцию с отказом 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-* — в разделе «Авторизация».