Аутентификация

Заголовок X-API-Key, формат ошибки 401, квоты по страницам и что происходит при перерасходе.

Заголовок

Каждый запрос к /v1/* требует ключ в заголовке X-API-Key:

X-API-Key: docai_sk_...

Ключ определяет клиента: тариф, остаток страниц и (если настроено) кастомную модель. Как получить ключ — в «Быстром старте».

OpenAI-совместимый вариант

Если ваш клиент уже настроен слать Authorization: Bearer <key> (как в OpenAI SDK), он тоже сработает — API принимает оба варианта. При наличии обоих заголовков приоритет у X-API-Key.

Ошибка авторизации — особый формат

Это частое место, где новичок теряет время: ошибка 401 устроена не так, как остальные ошибки API. Ошибки формы запроса приходят как {"detail": {code, message, details}}, ошибки обработки — как {success, error: {code, message}} (см. «Ошибки»), но отсутствующий или неверный ключ проверяется раньше — на уровне зависимости FastAPI, до эндпоинта — и приходит в третьей форме, со строковым detail:

{ "detail": "Missing API key. Include X-API-Key header." }

{ "detail": "Invalid API key." }

Оба случая — HTTP 401. Если ваш код парсит ошибки по пути error.code/error.message, для 401 добавьте отдельную ветку на detail — иначе парсер молча получит undefined.

Квоты и биллинг

Тариф определяет пакет страниц в месяц, а не жесткий потолок запросов:

Тариф	Пакет страниц/мес	Стоимость
Free (по умолчанию для нового ключа)	100 страниц	бесплатно
Старт	3 000 страниц	5 000 ₽
Про	25 000 страниц	35 000 ₽

Все цены НДС не облагаются (УСН). Перерасход не останавливает поток: каждая страница сверх пакета — 2,5 ₽, отдельной строкой в следующем счете.

Страница — единица объема, не физический лист:

страница = max(текст ÷ 2000 символов, площадь листа ÷ формат А4)
А1 = 8 страниц А4, А2 = 4, А3 = 2

Для обычного текстового документа на А4 считается по символам, для чертежей и крупноформатных листов — по площади: это та же логика, что и на странице цен. В каждом ответе приходит usage: {pages, sheets} — сколько страниц тарифицировано и сколько это физических листов, чтобы «восемь страниц из одного чертежа» не выглядели ошибкой счета.

Предохранители тарифа

Три независимых стопора срабатывают до тяжелой обработки — деньги не тратятся на запрос, который все равно будет отклонен:

Предохранитель	Что ограничивает	Ответ при срабатывании
Скорость	Страниц в минуту по вашему плану, скользящее окно 60 с	`429 RATE_LIMITED` + заголовок `Retry-After` — реальные секунды до следующей допустимой отправки, а не оценка
Потолок документа	Страниц в одном документе (для PDF считается по метаданным, без запуска парсинга)	`413 PAYLOAD_TOO_LARGE`, `details.max_pages_per_document`
Месячная квота	Пакет страниц плана за календарный месяц	`402 QUOTA_EXCEEDED`, `details.pages_used_this_month` и `details.pages_limit`

Квота — жесткий стоп по факту исчерпания, а не мягкое предупреждение; сбрасывается автоматически в начале календарного месяца. Пороги скорости и потолок документа растут вместе с планом; сколько страниц входит в пакет — на странице тарифов. Один документ, который помещается в потолок плана, проходит на пустом окне скорости, даже если он крупнее минутного лимита — иначе крупный документ отвергался бы навсегда.

Отдельного лимита «запросов в секунду» сверх этого нет. Второе практическое ограничение идет не от API, а от внешнего прокси: он режет соединение на 300 секунд. Для файлов, обработка которых может занять дольше (обычно — сканы от ~100 страниц), передавайте async: true и забирайте результат поллингом GET /v1/process/{task_id} — см. «/v1/process» → Асинхронный режим.

Кабинет: ключи без интеграции

Ключи не обязательно получать письмом: в кабинете вход по одноразовой ссылке, ключи выпускаются и отзываются самостоятельно, там же виден расход за месяц. Активных ключей на аккаунт — не больше пяти (422 KEY_LIMIT_REACHED), отзыв мягкий: ключ перестает работать, но остается в списке вместе с историей расхода. Подробно — в разделе «Кабинет и обработка без кода».

Обработка прямо в кабинете идет по сессии, без X-API-Key, и списывается на ваш активный ключ с максимальным тарифом.

Коды ошибок доступа

HTTP	Код	Когда
401	— (формат `{"detail": "..."}`, см. выше)	ключ отсутствует или неверен
422	`ANONYMIZATION_INCOMPLETE`	PII-граница `fail_closed`: скраб перед внешней LLM не дал гарантии чистоты — запрос к модели не выполнен. В `details.residual` только категории и счетчики, не сами значения
413	`FILE_TOO_LARGE`	файл больше 50 МБ (реестр для сверки — больше 20 МБ)
422	`UNSUPPORTED_FILE_TYPE`	формат файла не поддерживается — см. «Форматы и лимиты»
429	`RATE_LIMITED`	превышена скорость плана (страниц в минуту) — повторите через число секунд из заголовка `Retry-After`
413	`PAYLOAD_TOO_LARGE`	документ длиннее потолка страниц плана (`details.max_pages_per_document`)
402	`QUOTA_EXCEEDED`	месячная квота страниц исчерпана — поднимите тариф или дождитесь начала календарного месяца
422	`KEY_LIMIT_REACHED`	у аккаунта уже пять активных ключей — отзовите ненужный в кабинете
401	`CABINET_HEADER_REQUIRED`	доступ по сессии кабинета без заголовка `X-Requested-With: docai-cabinet` — касается только браузерного контура, не интеграции

Полный каталог ошибок — в разделе «Ошибки».