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

# Errors and troubleshooting

> Read error responses from the programmable worlds API and fix common causes.

## Error responses

Errors return a JSON body with a `detail` message:

```json theme={null}
{ "detail": "world not found" }
```

Validation errors on `POST /v1/worlds` also include an `errors` array naming
exactly what failed:

```json theme={null}
{
  "detail": "generated world failed schema validation",
  "errors": [
    "scene.states.opening.camera: required { static, dynamic } strings",
    "entrance.state 'missing' is not a defined state"
  ],
  "schemaVersion": "1.0"
}
```

## Status codes

| Code  | Meaning             | What to do                                                               |
| ----- | ------------------- | ------------------------------------------------------------------------ |
| `400` | Bad request         | A premise or a frame is required to create a world. Check your JSON.     |
| `401` | Unauthorized        | Missing, invalid, or revoked API key.                                    |
| `402` | Quota exceeded      | You hit a daily [quota](/pricing). Nothing was charged.                  |
| `403` | Forbidden           | Not permitted (e.g. forking a world you can't read; origin not allowed). |
| `404` | Not found           | Wrong id, or a resource that isn't your app's.                           |
| `422` | Validation failed   | The generated world failed the schema gate (`errors` lists why).         |
| `429` | Rate limited        | Honor `Retry-After`; back off.                                           |
| `503` | Backend unavailable | The quota/auth backend is briefly down (fail-closed). Retry shortly.     |

## Common causes

* **`400` on create** — neither `premise` nor a frame (`frame_url` / `frame_b64`)
  was supplied, or the body isn't valid JSON with `Content-Type: application/json`.
* **`401`** — using a publishable key (`pk_…`) where a secret key (`sk_…`) is
  required, or a revoked key.
* **`404` reading a world** — the world belongs to a different app. Worlds are
  scoped to the app that created them.
* **Unfetchable `frame_url`** — Alakazam fetches the URL server-side with no
  cookies or auth. Test it with a plain `curl` from a fresh environment; if it
  won't fetch, send the image inline as `frame_b64`.