# Errors and Recovery

Resolve permission, availability and state conflicts without duplicating a write.

## Errors and Retries

**403 worlds_read_only**

The deployment cannot register worlds. Use a writable deployment.

**404 unknown_reference**

The reference is unknown or outside this workspace. Check IDs and the token’s workspace.

**409 stale_object_base**

The state changed after you read it. Reread, reconcile, and submit against the new digest.

**422**

A request field or generated-world parameter is invalid. Read the error detail and correct the input.

Do not blindly retry a write after a lost connection: first inspect the world or saved entry to determine whether the change was applied. Capability availability and token permission are separate checks.

## Unavailable Is Not Unsupported

**available**

The server would attempt the operation. Inputs and state are still validated.

**unavailable**

Read the reason. A dependency or the world's state prevents this operation. Permission is separate: an operation can be available and still not permitted to this token.

**unsupported**

This kind of world, engine or role does not support the operation. Choose a supported operation.

**unknown**

A required fact is outside what this caller may read. Do not guess availability.

Read capability descriptors when your UI needs to decide whether to offer an action. Handle the write’s own refusal too: state can change between discovery and submission.

## Recover a Failed Edit

For a stale base, read the version again and reconcile your intended change against its new state digest. Do not silently overwrite another client’s edit.

After a network timeout, read the affected world or saved entry first. Submit again only after determining whether the original change took effect. Use a documented idempotency field when the operation offers one; do not invent a global retry key.

## Check the Installation

For connection failures, verify the API address and /readyz. Optional workers and model providers have their own prerequisites; a running server does not establish that each service is ready.

[Installation](/docs/self-hosting)

[Authentication](/docs/authentication#docs-authentication-failures)