Ответы и ошибки
Коды ответов, причины отказа при загрузке и поля для диагностики.
Успешный ответ всегда содержит поле data. У списков рядом стоит pagination или meta.
Ошибка приходит в одном и том же виде:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "File content does not match declared MIME type for \"report.xlsx\"",
"details": { }
}
}Поле message написано по-английски и предназначено для того, кто разбирает сбой, — не
показывайте его сотруднику как есть.
Коды
| Код | Что произошло | Что делать |
|---|---|---|
400 | Запрос не прошёл проверку. При загрузке — ни один файл не сохранён | Читать details.reason, таблица ниже |
401 | Ключ не передан, передан не в том виде, отозван или истёк | Проверить заголовок; при отзыве — получить новый ключ |
403 | Либо папка не входит в список ключа, либо запрос вообще не для ключей | Сверить папку с ответом /mine; список того, что ключу закрыто, — в разделе «Папки и файлы» |
404 | Папки с таким идентификатором нет | Перечитать /mine: папку могли удалить |
Причины отказа при загрузке
У ответа 400 на загрузку есть поле error.details.reason — короткая строка из закрытого
списка. Разбирайте именно её: message со временем может измениться, reason — нет.
reason | Что произошло |
|---|---|
no_files | В запросе нет ни одного файла |
file_type_not_allowed | Расширение файла не входит в список поддерживаемых |
content_mime_mismatch | Внутри файла лежит не то, что обещает расширение |
doc_size_exceeded | Документ больше 200 МБ |
multer_limit | Превышен предел на число файлов или на общий объём запроса |
filename_too_long | Имя файла слишком длинное — его отказалась принять файловая система |
relative_paths_not_array | relativePaths — не массив строк |
relative_paths_length_mismatch | Длина relativePaths не совпала с числом файлов |
relative_paths_invalid | Один из путей не прошёл проверку — например, пытался выйти за пределы папки |
subpath_limit_exceeded | В папке уже максимальное число подпапок |
У причины content_mime_mismatch есть подробности: имя файла, что портал распознал внутри и
что обещало расширение.
{
"error": {
"code": "VALIDATION_ERROR",
"message": "File content does not match declared MIME type for \"report.xlsx\"",
"details": {
"reason": "content_mime_mismatch",
"filename": "report.xlsx",
"verdict": "undetectable_content",
"detectedMime": null,
"declaredExt": ".xlsx",
"sizeBytes": 87
}
}
}Три значения verdict: unknown_extension — такого расширения портал не знает;
undetectable_content — по первым байтам не удалось понять, что это; mime_mismatch —
удалось, и это не то.
undetectable_content часто означает, что файл пуст или обрезан. Такая ошибка возникает,
если загрузчик отправляет файл до окончания записи на диск.
Ошибка на одном файле отменяет весь запрос
Проверки идут до сохранения, и первая же неудача отменяет запрос целиком: если из пятидесяти
файлов не прошёл один, не сохранится ни один. Отправляйте файлы такими порциями, которые
можно безопасно отправить повторно, и не считайте 400 частичным успехом.
Исключение одно — медиафайлы при выключенном переводе записей в текст. Они не ошибка: запрос
проходит, такие файлы возвращаются в skippedFiles, остальные сохраняются.
Данные для диагностики
Каждое обращение по ключу портал записывает, и администратор видит эту запись целиком: кнопка «Логи» в строке ключа открывает журнал вызовов — дата, действие, папка, число файлов, объём, адрес, код ответа и длительность. Строки загрузки разворачиваются и показывают имена файлов.
По журналу определите, дошёл ли запрос и с каким кодом ответил портал. Записи старше девяноста дней портал удаляет.