Errors, versions, and compatibility

Check the HTTP status first, then parse the body. Successful responses contain content. Documented API errors contain error, whose value can be a string or an object.

HTTP errors and responses

HTTP	Cause	What to check
400	Missing or incorrectly formatted ID	Whether a six-digit export ID was supplied
404	Export not found or expired	The ID from the publication dialog and the publication time
429	Request limit exceeded	The wait specified in Retry-After
500	Request or stored export processing failed	The error text; for Invalid JSON, you can publish the project again
503	API storage is unavailable	Service availability; immediate retries do not resolve the underlying cause

HTTP 400: missing or invalid ID

{"error":"ID is missing"}

HTTP 404: nonexistent or expired ID

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

HTTP 429: request limit exceeded

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

The Retry-After header and retryAfterSeconds field specify the wait in seconds. It is 45 seconds in this example; use the value in your response. See Request limits for the two active limits and their headers.

HTTP 500: internal request processing error

{"error":"Internal error"}

HTTP 500: stored export data cannot be processed

{"error":"Invalid JSON"}

HTTP 503: the storage connection is unavailable

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

These are the formats returned by the API itself. Network or infrastructure failures can result in a different format, including HTML or an empty body. A network failure may also end the request before any HTTP response arrives. A JSON parsing error alone therefore does not identify the cause.

Temporary IDs

A publication remains available for 10 minutes. After that, the API returns the same 404 as for a nonexistent ID. The response body does not distinguish these cases.

Make sure you copied the export ID, not a model catalog ID. If it has expired, publish again from the editor and use the new ID. Retrying the old ID does not restore the export or extend its lifetime. See Requests, parameters, and export lifetime.

Compatibility of retrieved data

200 means the data was retrieved successfully. Using it depends on your integration supporting the selected Minecraft version and the fields in the export.

Animations, sounds, hitboxes, and project_id may be absent. An absent optional field is not itself an API error. When reading passengers, remember that its strings contain SNBT: another JSON.parse() call does not convert them into Minecraft objects.

If the data arrives but a model is not created or events do not play, check the JSON structure and export contents. Execution failures inside an integration are not HTTP API errors.

What the versions mean

Value	Meaning
content.version, such as "1.21.4"	Minecraft version selected for export
content.meta.schema, currently 1	Animation and sound metadata schema version
The version argument of editorAPI.exportToJSON()	Numeric index of a version in the editor interface
BDEngine build version	Version of the editor that prepared the export; there is no separate mandatory field for it here

Do not interpret the numeric editorAPI index as a Minecraft version string. The current implementation maps it to the selected version and writes that string to content.version. See Projects, lists, and geometry for the method signature.

The JSON may evolve with the editor. Do not silently treat an unknown metadata schema as schema 1. If an older export lacks meta, that is not a basis for guessing the frame step. See JSON structure for field definitions.