Errors and troubleshooting

Error responses

The World API uses standard HTTP status codes. Most errors return a JSON body with a detail field that describes the problem:

{
  "detail": "Failed to download asset from https://example.com/image.jpg. Please check the URL and try again."
}

Schema validation errors (422) return detail as an array, with one entry per invalid field:

{
  "detail": [
    {
      "loc": ["body", "world_prompt", "type"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Some requests are rejected before they reach validation and come back with a generic message and no detail field, such as Bad request. The most common cause is a body that isn’t valid JSON — see Request body is not valid JSON.

Many responses include a request_id. It’s a trace identifier for the World Labs team, not something you can look up yourself. Keep it and include it (with your endpoint and request body, API key redacted) when you contact support@worldlabs.ai.

Status codes

Status	Meaning	What to do
`400` Bad request	The request was invalid, or the prompt/input violated content policy.	Read `detail` when present. See common causes below.
`402` Payment required	The account has insufficient API credits.	Add credits or enable auto-refill on the billing page. API credits are separate from Marble app credits — see the FAQ.
`404` Not found	The world, operation, or media asset doesn’t exist or isn’t owned by your API user.	Verify the ID and that it was created with the same API key.
`422` Unprocessable entity	The body didn’t match the request schema.	Read the field path in each `detail[]` entry and fix that field.
`429` Too many requests	You exceeded a rate limit.	Back off and retry. See Rate limits.
`500` Internal server error	The request couldn’t be processed.	Retry after a short delay; contact support if it persists.

Finding the specific reason

Where the failure reason lives depends on how the call fails:

Immediate HTTP errors (the worlds:generate call itself returns 4xx): read the status code and the detail field, then apply the fixes below.
Generation failures happen later. A worlds:generate call that returns 200 with an operation_id can still fail during generation. Poll GET /marble/v1/operations/{operation_id}; when done is true with a non-null error, read error.code and error.message.

Common 400 causes

Request body is not valid JSON

A frequent symptom is a generic Bad request with no detail, even though the same payload works with curl. Some HTTP clients send a language-native object or map through its default string conversion instead of serializing it to JSON. That produces a body like this:

{model=marble-1.0, permission={allow_id_access=false, public=false}, world_prompt={...}}

That isn’t JSON — it has unquoted keys, = instead of :, and no string quoting, so it’s rejected before it reaches the API. Valid JSON looks like {"model":"marble-1.0",...}. Fix: serialize the payload to a JSON string before sending, and set Content-Type: application/json. Log the exact bytes you pass to your HTTP client to confirm they’re JSON.

Image or video URL can’t be fetched

When you use source: "uri", World Labs fetches the URL from its servers with no cookies, authentication, or referer. Hotlink-protected or login-gated hosts (some CDNs and image-search result links) block these server-side fetches, which returns a 400. Test the URL from a fresh environment — for example curl with no cookies or referer. If it doesn’t return the raw image or video bytes, the API can’t use it either. Use one of these instead:

Upload the file as a media asset, then reference its media_asset_id. See Prepare a media asset upload and the Quickstart upload flow.
Inline a small file with source: "data_base64".

Content policy

A prompt or input image or video can be rejected for content-policy reasons, also as a 400. Adjust the input and retry.

Invalid model

model must be one of the supported values. See Models for the current list.

Get started

Examples

Reference

Support & billing

Errors and troubleshooting

Error responses

Status codes

Finding the specific reason

Common 400 causes

Request body is not valid JSON

Image or video URL can’t be fetched

Content policy

Invalid model

​Error responses

​Status codes

​Finding the specific reason

​Common 400 causes

​Request body is not valid JSON

​Image or video URL can’t be fetched

​Content policy

​Invalid model

Error responses

Status codes

Finding the specific reason

Common 400 causes

Request body is not valid JSON

Image or video URL can’t be fetched

Content policy

Invalid model