> ## Documentation Index
> Fetch the complete documentation index at: https://docs.worldlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and troubleshooting

> How to read World API error responses and fix the most common failures, including 400 Bad request

## Error responses

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](#request-body-is-not-valid-json).

<Note>
  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](mailto:support@worldlabs.ai).
</Note>

## 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](#common-400-causes) below.                                                                                                  |
| `402` Payment required      | The account has insufficient API credits.                                           | Add credits or enable auto-refill on the [billing page](https://platform.worldlabs.ai/billing). API credits are separate from Marble app credits — see the [FAQ](/api/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](/api/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}`](/api/reference/operations/get);
  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:

```text theme={null}
{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](/api/reference/media-assets/prepare-upload) and
  the [Quickstart upload flow](/api#image-input).
* 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](/api/models) for the
current list.