# Ошибки HTTP API

← [К разделу «HTTP API»](README.md)

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

```json
{
  "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` и полное тело,
если оно содержит персональные данные.