Коды ошибок

При неудачном запросе API возвращает JSON-ответ с машиночитаемым code и читаемым message:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the error"
  }
}

Поле code стабильно и безопасно для сопоставления в логике вашего приложения. Поле message может меняться со временем и предназначено для логирования и отладки.

Справочник кодов ошибок

Код	HTTP-статус	Описание	Повторяемая	Решение
UNAUTHORIZED	401	Отсутствующий, недействительный или просроченный токен аутентификации	Нет	Проверьте, что ваш API-ключ действителен и не просрочен
KEY_EXPIRED	401	Срок действия API-ключа истек	Нет	Создайте новый API-ключ в панели управления или через API
FORBIDDEN	403	Аутентифицирован, но не авторизован для данного ресурса	Нет	Вы можете получить доступ только к своим собственным ресурсам
NOT_FOUND	404	Запрашиваемый ресурс не существует	Нет	Проверьте правильность ID ресурса
VALIDATION_ERROR	400	Тело запроса не прошло валидацию схемы	Нет	Проверьте обязательные поля и типы данных на соответствие схеме
INVALID_MIME_TYPE	400	Загруженный файл имеет неподдерживаемый MIME-тип	Нет	Используйте поддерживаемый тип файла (PDF или DOCX)
FILE_TOO_LARGE	400	Загруженный файл превышает лимит 10 МБ	Нет	Уменьшите размер файла или разделите на меньшие документы
MAX_KEYS_REACHED	400	Достигнут максимум в 10 активных API-ключей	Нет	Отзовите неиспользуемые ключи перед созданием новых
USAGE_LIMIT_EXCEEDED	429	Достигнут ежемесячный лимит извлечений	Нет	Перейдите на более высокий план или дождитесь следующего периода оплаты
INTERNAL_ERROR	500	Непредвиденная серверная ошибка	Да	Повторите с экспоненциальной задержкой. Если проблема сохраняется, обратитесь в поддержку
NOT_CONFIGURED	501	Необходимый серверный сервис не настроен	Нет	Обратитесь в поддержку -- это указывает на проблему конфигурации сервера
EXTRACTION_FAILED	502	Обработка извлечения ИИ не удалась	Да	Повторите -- может быть временная проблема. Проверьте, что PDF валиден и читаем
EXTRACTION_PARSE_ERROR	502	ИИ вернул ответ, который не удалось разобрать как JSON	Да	Повторите -- ИИ может выдать корректный результат при следующей попытке

Повторяемые ошибки

Повторять следует только следующие коды ошибок:

• INTERNAL_ERROR -- Непредвиденная ошибка на стороне сервера.
• EXTRACTION_FAILED -- Процесс извлечения ИИ не удался, часто из-за временных проблем.
• EXTRACTION_PARSE_ERROR -- ИИ вернул некорректный вывод, который не удалось разобрать.

При повторных попытках используйте экспоненциальную задержку, начиная с 1 секунды, с максимумом в 3 попытки:

Попытка	Задержка
1-я повторная	1 секунда
2-я повторная	2 секунды
3-я повторная	4 секунды

Если запрос по-прежнему не удается после 3 повторных попыток, залогируйте ошибку и сообщите о ней пользователю или в вашу систему мониторинга.

Полное руководство по реализации логики повторных попыток см. в разделе Обработка ошибок.

Сводка HTTP-кодов статуса

Статус	Значение
200	Успех -- запрос выполнен успешно
400	Некорректный запрос -- ошибка валидации, недопустимый тип файла, слишком большой файл или лимит ключей достигнут
401	Не авторизован -- аутентификация не удалась (отсутствующий, недействительный или просроченный токен)
403	Запрещено -- аутентифицирован, но не авторизован для запрашиваемого ресурса
404	Не найдено -- запрашиваемый ресурс не существует
429	Слишком много запросов -- ежемесячный лимит извлечений превышен
500	Внутренняя ошибка сервера -- непредвиденная ошибка на стороне сервера
501	Не реализовано -- необходимый серверный сервис не настроен
502	Ошибка шлюза -- извлечение или парсинг ИИ не удались