Errors and troubleshooting

​

Error responses

{ "detail": "world not found" }

{
  "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

​

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: the API key is missing, invalid, or revoked.
• 403 (wrong key type or missing scope): using a publishable key (pk_…) where a secret key (sk_…) is required, or a valid key that lacks the required scope (API key missing required scope: …).
• 403 on /sessions/connect or a character turn: the session was ended (via /sessions/end) or killed, so reconnecting/refreshing is refused, or the session token was minted for a different character than the one you’re calling. Mint a fresh session token.
• 404 reading a world: the world belongs to a different app, or you’re reading it with a key in the other mode. Worlds are scoped to the app that created them, and test and live data never see each other.
• 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.