Ошибки, версии и совместимость

Сначала проверяйте HTTP-статус, затем разбирайте тело. Успешный ответ содержит content, а предусмотренные ошибки API - поле error. Его значение может быть строкой или объектом.

HTTP-ошибки и ответ

HTTP	Причина	Что проверить
400	ID отсутствует или имеет неверный формат	Передан ли шестизначный ID экспорта
404	Экспорт не найден или срок действия истёк	ID из окна публикации и время экспорта
429	Превышено ограничение запросов	Ожидание в Retry-After
500	Ошибка обработки запроса или сохранённых данных	Текст ошибки; для Invalid JSON можно заново опубликовать проект
503	Хранилище API недоступно	Доступность сервиса; немедленные повторные запросы не устраняют причину

HTTP 400: отсутствующий или неверный ID

{"error":"ID is missing"}

HTTP 404: несуществующий или истёкший ID

{"error":"ID does not exist or is outdated"}

HTTP 429: превышение частоты запросов

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Please try again later.",
    "retryAfterSeconds": 45
  }
}

Заголовок Retry-After и поле retryAfterSeconds указывают ожидание в секундах. В этом примере оно равно 45 секундам; фактическое значение берите из ответа. Два действующих лимита и их заголовки описаны в разделе Ограничения запросов.

HTTP 500: внутренняя ошибка обработки запроса

{"error":"Internal error"}

HTTP 500: невозможно обработать сохранённые данные экспорта

{"error":"Invalid JSON"}

HTTP 503: подключение к хранилищу недоступно

{"error":"PostgreSQL is not connected."}

Это форматы ошибок, возвращаемых самим API. При сетевом или инфраструктурном сбое ответ может иметь другой формат, включая HTML или пустое тело. Сетевая ошибка также может завершить запрос до получения HTTP-ответа. Поэтому ошибка разбора JSON сама по себе не определяет причину сбоя.

Временный ID

Публикация доступна 10 минут. После этого API возвращает тот же 404, что и для несуществующего ID: по телу ответа различить эти случаи нельзя.

Проверьте, что скопирован ID экспорта, а не ID модели в каталоге. Если срок истёк, повторите экспорт из редактора и используйте новый ID. Повторный запрос со старым ID не восстанавливает публикацию и не продлевает её срок. Все правила: Запрос по ID, параметры и срок жизни.

Совместимость полученных данных

200 означает успешное получение данных. Их применение зависит от поддержки вашей интеграцией выбранной версии Minecraft и конкретных полей экспорта.

В ответе могут отсутствовать анимации, звуки, хитбоксы и project_id. Отсутствие необязательного поля само по себе не является ошибкой API. При чтении passengers учитывайте, что строки внутри массива имеют формат SNBT: повторный JSON.parse() не превращает их в объекты Minecraft.

Если данные получены, но модель не создаётся или события не воспроизводятся, сверьте структуру JSON и состав экспорта. Ошибки исполнения внутри интеграции не являются HTTP-ошибками API.

Смысл версий

Значение	Что оно означает
content.version, например "1.21.4"	Версия Minecraft, выбранная при экспорте
content.meta.schema, сейчас 1	Версия схемы метаданных анимаций и звуков
Аргумент version у editorAPI.exportToJSON()	Числовой индекс версии в интерфейсе редактора
Версия сборки BDEngine	Версия редактора, подготовившего экспорт; отдельного обязательного поля с ней здесь нет

Числовой индекс editorAPI нельзя интерпретировать как строку версии Minecraft. Текущая реализация переводит его в выбранную версию и записывает строку в content.version. Сигнатура метода: Проекты, списки и геометрия.

Состав JSON может развиваться вместе с редактором. Неизвестную версию схемы метаданных не следует молча считать схемой 1, а отсутствующее meta в старом экспорте не даёт основания угадывать шаг кадров. Значения полей описаны в статье Структура JSON.