Skip to main content

​
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

StatusMeaningWhat to do
400 Bad requestThe request was invalid, or the prompt/input violated content policy.Read detail when present. See common causes below.
402 Payment requiredThe 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 foundThe 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 entityThe body didn’t match the request schema.Read the field path in each detail[] entry and fix that field.
429 Too many requestsYou exceeded a rate limit.Back off and retry. See Rate limits.
500 Internal server errorThe 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:

​
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.