ave-cms/help/api/errors.md

Ошибки HTTP API

← К разделу «HTTP API»

Единый формат ошибки:

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "Проверьте данные документа",
    "fields": {
      "title": "Укажите название документа"
    }
  }
}

fields присутствует у ошибок валидации и содержит машинный путь поля → текст. Не привязывайте логику клиента к русскому message; используйте code и HTTP-статус.

HTTP	error.code	Причина
400	invalid_json	Тело не является корректным JSON-объектом.
401	unauthorized	Нет Bearer, токен/scope/роль недействительны.
404	not_found	Документ не найден или удалён.
413	payload_too_large	Тело больше 2 МБ или не прочитано.
415	unsupported_media_type	Для записи не указан application/json.
422	validation_failed	Ошибка документа, поля, hook или кода рубрики.
429	rate_limited	Превышено 120 запросов за 60 секунд.
500	save_failed	Непредвиденная ошибка сохранения.

Повтор запроса

• 400, 401, 404, 413, 415, 422 не повторяйте без исправления запроса или доступа.
• При 429 соблюдайте Retry-After и exponential backoff.
• При 500 допустим ограниченный повтор только для идемпотентной операции.

Создание через POST не имеет внешнего idempotency-key в v1. После сетевого обрыва сначала попробуйте найти документ по заранее заданному уникальному alias, а не отправляйте POST вслепую второй раз. Для критичной массовой интеграции используйте стабильный guid и собственный модуль синхронизации.

Журналирование клиента

Записывайте метод, URL без токена, HTTP-статус, error.code, request ID внешней системы и длительность. Не журналируйте заголовок Authorization и полное тело, если оно содержит персональные данные.