Skip to main content

​
Error responses

Errors return a JSON body with a detail message: 
{ "detail": "world not found" }
Validation errors on POST /v1/worlds also include an errors array naming exactly what failed: 
{
  "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

CodeMeaningWhat to do
400Bad requestA premise or a frame is required to create a world. Check your JSON.
401UnauthorizedMissing, invalid, or revoked API key.
402Quota exceededYou hit a daily quota. Nothing was charged.
403ForbiddenNot permitted (e.g. forking a world you can’t read; origin not allowed).
404Not foundWrong id, or a resource that isn’t your app’s.
422Validation failedThe generated world failed the schema gate (errors lists why).
429Rate limitedHonor Retry-After; back off.
503Backend unavailableThe 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.