Platform API error

world_not_allowed

world_not_allowed is the 403 error returned when the API key's world list does not include the world you are calling or subscribing to.

Updated November 6, 2026

HTTP status: 403
Code: world_not_allowed
API: Platform API v1

Returned when

A key limited to some worlds calls a tool of another world, or subscribes to events from a world outside its list. A scope decides what a key may do; its world list decides where, and both must allow the call.

What to do

Use a key whose worlds include this one, or ["*"]. details.worlds shows the key's list.

Example answer

HTTP/1.1 403
content-type: application/json

{
  "error": {
    "code": "world_not_allowed",
    "message": "This key may not call <world>."
  }
}

Related errors

insufficient_scope The key does not hold the scope this endpoint needs.
invalid_world A subscription names a world that does not exist.

What it means

The Platform API returns world_not_allowed with HTTP 403 when the key making the request is not allowed in the world involved. The key's world list does not include this world. A scope decides what a key may do; its world list decides where, and both must allow the call.

The message names the block: "This key may not call <world>." for a tool call, or "This key may not subscribe to <worlds>." for an event subscription. The response uses the standard error shape {"error":{"code":"…","message":"…","hint":"…"}}. Codes are stable, so match on error.code, never on the message.

This is an authorization result, not a missing resource or malformed request. The key is recognized, but its world list does not cover the requested world.

Why you are seeing it

You see it when a key limited to some worlds calls a tool of another world, or subscribes to events from a world outside its list. The scope may allow the action, but the world list still blocks the request because both checks must pass.

The same response covers tool calls and event subscriptions. For a tool call, the message names the single world. For a subscription, it can name the worlds the key may not subscribe to. details.worlds shows the key's list, which shows where the key may operate.

Check the world you are targeting against details.worlds before changing scopes or keys. A key with the right scope but the wrong world list will keep returning world_not_allowed.

How to fix it

Read details.worlds from the error and compare it with the world in your request. Then use a key whose worlds include this one. A world list of ["*"] includes all worlds. For a subscription, make sure the key's list covers every world in it.

If the key is shared across jobs, split the work by world and give each job a key whose list matches the worlds it needs. Retrying the same request with the same key returns the same 403. Changing a scope alone does not widen the world list; scope and world list are separate checks.

For triage, check the related codes. world_not_allowed points to the world list, insufficient_scope points to what the key may do, and invalid_world is a separate code. Match on error.code to tell them apart.

Handling it in code

Branch on error.code == "world_not_allowed" and treat it as a permanent authorization failure for that key and world. Do not retry in a loop. Log the message, the requested world, and details.worlds to see the gap.

If your integration can choose a key, select one whose world list includes the target world or ["*"]. If it cannot, surface a clear configuration error to the operator instead of retrying.

Use the same handling for tool calls and event subscriptions. For subscriptions, validate the full world set against details.worlds before opening it. Keep the parser generic: read error.code, error.message, error.hint, and details. The messages include "This key may not call <world>." and "This key may not subscribe to <worlds>.".

Questions

What does HTTP 403 world_not_allowed mean?

The key's world list does not include the world you are calling or subscribing to. The key may have the right scope, but the world check failed. Use a key whose worlds include that world or ["*"].

How do I see which worlds a key can use?

details.worlds in the error shows the key's list. Compare it with the world in your request, then choose a key whose list includes the target world or ["*"].

Does fixing the scope clear world_not_allowed?

No. A scope decides what a key may do, and the world list decides where; both must allow the call. Changing the scope does not add a world to the key's list. Use a key whose worlds include the target world.

Keys, plans and usage live in the console: rotate keys, add webhook endpoints, see the last 30 days.

Open the console Plans

Written from the OneLifeVibe tool registry and platform configuration, and checked automatically before publishing. Something wrong? Tell us.