Идемпотентность, лимиты и ошибки
Повторы запросов и временные сбои.
Idempotency-Key — до 128 символов. В течение 24 часов одинаковый запрос с тем же ключом
вернёт прежний результат и не вызовет модель повторно. Изменённое тело, включая имя файла,
даёт 409 idempotency_conflict. Ключ ограничен вашим клиентом.
При потере HTTP-ответа повторяйте тот же запрос с тем же ключом. Если сохранённый результат
имеет status=failed и вы хотите запустить обработку заново, используйте новый ключ.
Файл — до 15 МБ по умолчанию. Проверка — до 45 секунд плюс время передачи файла.
Стандартный лимит клиента — 120 проверок в минуту. Дополнительно сервис ограничивает
число одновременно выполняемых проверок; при заполнении слотов возвращает 503 и Retry-After. Асинхронный режим в v1 отсутствует.
| HTTP | Код | Что делать |
|---|---|---|
| 401 | unauthorized / invalid_credentials | Проверить ключ доступа |
| 403 | tenant_disabled / profile_forbidden | Обратиться к команде Kvitera |
| 404 | not_found | Проверить идентификатор и клиента |
| 409 | processing | Подождать Retry-After и повторить чтение |
| 409 | idempotency_conflict | Использовать новый ключ для изменённого запроса |
| 413 | upload_too_large | Уменьшить файл |
| 422 | validation / unknown_profile | Исправить параметры |
| 429 | rate_limit | Подождать указанное в Retry-After число секунд |
| 503 | overloaded / database_unavailable | Повторить позднее |
Ошибки API имеют вид {"error":{"code":"...","message":"...","details":{}}}.
В завершённом HTTP-запросе технический сбой проверки имеет HTTP 200 и status=failed:
коды deadline, ingest_timeout, ingest_unavailable, vlm_unavailable,
storage_unavailable, database_unavailable, interrupted.
Результат всегда требует review; временный сбой не означает подделку.