Ошибки и деградация

API различает два принципиально разных сигнала: «запрос не выполнен» (HTTP-ошибка, тела результата нет) и «запрос выполнен, но результату стоит не полностью доверять» (200 OK, но extraction_status и warnings[] говорят, что часть данных — не более чем лучшая попытка). Второе — не баг, а осознанная деградация: сервис отдает то, что смог, вместо молчаливого падения.

Три формы тела ошибки

Это первое, обо что спотыкается парсер ошибок на клиенте: форм три, и они отличаются по уровню, на котором ошибка поймана.

1. Ошибки формы запроса (валидация /v1/process) — HTTP 422, поле detail — объект:

{
  "detail": {
    "code": "PROMPT_REQUIRES_SCHEMA",
    "message": "prompt без output_schema не поддерживается…",
    "details": {}
  }
}

2. Ошибки обработки (модель, парсинг, NDA-граница, размер файла) — привычный конверт:

{
  "success": false,
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File size 62914560 exceeds maximum 52428800 bytes",
    "details": { "size": 62914560, "max_size": 52428800 }
  }
}

3. Ошибка ключа — HTTP 401, detail — обычная строка:

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

Ключ проверяется раньше эндпоинта, поэтому формат отличается от обеих предыдущих форм. Подробнее — в разделе «Аутентификация».

Практическое правило разбора: сначала detail?.code, затем error?.code, затем detail как строка.

Каталог кодов

Форма запроса — 422, тело {"detail": {code, …}}

Обработка — тело {"success": false, "error": {…}}

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

Срабатывают до тяжелой обработки — за отклоненный запрос страницы не списываются. Механика и пороги — в «Аутентификации».

Остальное

Коды стабильны — это часть контракта; список аддитивный: новые коды могут появляться, существующие не переименовываются.

extraction_status

Приходит в metadata при 200 OK и отвечает на вопрос «что вообще получилось», независимо от HTTP-кода:

Это 200 OK в каждом случае. Проверяйте extraction_status так же внимательно, как HTTP-код: 200 означает «запрос обработан», а не «данные надежны».

warnings[] — структурные предупреждения

Каждый warning — {code, field, severity, message}. field — путь до поля (supplier.inn, items[0].amount, documents[1]) или $document для документа целиком. severity: info (к сведению) → low → medium (стоит перепроверить) → high (скорее всего неверно).

{
  "warnings": [
    {
      "code": "invalid_inn_length",
      "field": "supplier.inn",
      "severity": "high",
      "message": "ИНН «77» имеет некорректную длину…"
    }
  ]
}

Источников два, и они дополняют друг друга.

1. Проверки извлеченных данных

Работают всегда, независимо от вида задачи. Валидатор не только предупреждает, но и обнуляет заведомо неверное значение — например party2, дословно повторяющую party1.

2. Предупреждения самого эндпоинта

Проверки «пусто/слишком мало текста» применяются только к файловому входу: короткий text вы прислали сами и осознанно.

Практика: как обрабатывать деградацию на своей стороне

1. Проверяйте HTTP-статус и extraction_status/warnings[]. 200 OK означает «запрос обработан», а не «данным можно верить».
2. На high-warning по конкретному полю не показывайте значение пользователю как окончательное без пометки. На fallback — рассмотрите повторный вызов с более узкой схемой или ручную проверку.
3. parse_empty — сигнал о документе, а не о запросе: повтор с тем же файлом даст тот же результат. Нужен другой файл или лучшее качество скана.
4. На 422 ANONYMIZATION_INCOMPLETE повтор скорее всего повторит ошибку — это осознанный отказ границы, а не временный сбой; нужен другой документ или self-hosted-контур (см. цены → «Бизнес»).
5. На 502/503 (LLM_RESULT_NOT_OBJECT, PARSING_ERROR, EXTRACTION_ERROR, PROVIDER_UNAVAILABLE) — это временная деградация после исчерпания fallback-цепочки, повторите запрос с задержкой.
6. На 503 QUEUE_FULL повторите через число секунд из заголовка Retry-After — это штатный ответ заполненной очереди, а не сбой. INTERRUPTED_BY_RESTART в теле поллинга — сигнал отправить документ заново: страницы за прерванную обработку не списываются повторно.