Ошибки и повторные запросы API v2

Пример:

Коды ответов

HTTP	Когда возникает	Действие интегратора
`201`	Страница создана	Сохранить `url`, `pdf_url`, `page_slug` и при необходимости `page_id`
`200`	Результат сущности обновлён	Проверить `updated_pages`
`400`	Не хватает масок или шаблон не отрендерился	Исправить данные/маски; не повторять вслепую
`401`	Нет или неверен API-ключ	Проверить `X-Api-Key`
`404`	Шаблон не найден в пространстве ключа	Проверить `template_id` и ключ
`409`	Переданный `page_slug` уже занят	Передать другой slug или не передавать его
`415`	Запрос создания не `multipart/form-data`	Использовать form-data, а не JSON
`422`	Неверные поля формы или schema validation	Проверить имена `data.`, `rows.`, типы и формат slug
`402`	Не хватает баланса для платной операции	Пополнить баланс через VARICA и повторить операцию
`5xx`	Внутренняя/внешняя временная ошибка	Повторить с ограниченным количеством попыток

Ошибка обязательных масок

Пример:

{
  "detail": {
    "message": "Required template variables are missing",
    "missing_variables": ["client.name", "tables.price"],
    "required_variables": ["client.name", "tables.name", "tables.price"],
    "provided_variables": ["tables.name"]
  }
}

required_variables — все маски шаблона, включая тему и Table v2. provided_variables — то, что сервис увидел в data.*. Табличные rows.* в этой диагностике могут выглядеть отдельно от обычных полей, поэтому их нужно сверять с разделом табличных строк.

Повторные запросы

Создание страницы не является идемпотентным: два одинаковых успешных POST /api/v2/pages создадут две страницы и две операции списания. Если внешняя система повторяет запрос после сетевой неопределённости, ей нужно хранить свой факт успешного ответа и не отправлять повтор без необходимости.

source_entity_id не делает создание идемпотентным: одна сущность может осознанно иметь несколько КП.

Для POST /api/v2/entity-results повтор безопасен: он повторно устанавливает тот же статус страницам той же организации.

Минимальная стратегия повтора

Не повторять 400, 401, 404, 409, 415, 422 до исправления запроса.
Для 5xx использовать 1–3 повтора с растущей задержкой.
При тайм-ауте собственного клиента сначала проверить свой журнал: мог прийти успешный ответ, но не успеть сохраниться у вызывающей системы.
Не делать автоматические параллельные повторы создания одной и той же страницы.