---
title: "Runtime Error Catalog"
description: "Sources: `server/src/modules/runtime/errors/runtimeErrorCatalog.ts:RUNTIME_ERROR_CATALOG`."
engineVersion: v1.0.234
date: 2026-09-28
license: "(c) Gessa, proprietary. Cite with attribution to https://gessa.ai/docs/. Terms: https://gessa.ai/terms/."
canonical: https://gessa.ai/docs/spec/generated/error-catalog/
---
<!-- GENERATED FILE: do not edit by hand. -->
<!-- Regenerate with `npm run gen-docs`. -->

Sources: `server/src/modules/runtime/errors/runtimeErrorCatalog.ts:RUNTIME_ERROR_CATALOG`.

# Runtime Error Catalog

This generated snapshot is derived from `RUNTIME_ERROR_CATALOG` in `server/src/modules/runtime/errors/runtimeErrorCatalog.ts`. It is the closed taxonomy of runtime gateway error codes: every runtime failure reaches the boundary already carrying one of these machine codes, and the boundary maps that code to the static player-safe copy recorded here.

The frontend presentation registry (`web_client/spa/src/runtime/generated/runtimeErrorRegistry.gen.ts`) is generated from this same catalog by `scripts/generate-runtime-error-registry.mjs`, so the player title, player message, category, retryable, and terminal values on both sides cannot drift.

The operator description is log-facing and is not shown to a player.

Error code count: `64`.
Category count: `10`.
Engine-contract code prefix: `runtime_engine_contract_`.

## Categories

Every code belongs to one closed top-level category. The disposition is the total, compile-checked classification from `runtimeErrorCategoryDisposition`.

| Category | Disposition | Code count |
| --- | --- | --- |
| `auth` | denied | 8 |
| `schema_violation` | malformed | 7 |
| `release_mismatch` | stale_release | 10 |
| `boot_failure` | booting | 9 |
| `overload` | shedding | 6 |
| `transport` | transport | 5 |
| `lifecycle` | lifecycle | 13 |
| `revoked` | revoked | 1 |
| `capacity` | at_capacity | 2 |
| `rate_limited` | throttled | 3 |

## Error codes

| Code | Category | Retryable | Terminal | Player title | Player message | Description |
| --- | --- | --- | --- | --- | --- | --- |
| `runtime_auth_invalid` | `auth` | no | yes | Sign in to play | We couldn't verify your game session. Refresh the page or sign in again to continue. | Runtime player credential MAC/signature invalid, malformed, or an impostor token: genuine auth failure. Terminal. |
| `runtime_credential_expired` | `auth` | yes | no | Reconnecting | Refreshing your game session. | Runtime player credential expired (expiresAtMs <= now). Sliding re-mint over the live socket (03 section 2); degraded, not terminal. |
| `runtime_connection_unverified` | `auth` | yes | yes | Sign in to play | Refresh the page or sign in again to continue. | Legacy unverified-connection catch-all. Migrate throw sites to runtime_auth_invalid / runtime_credential_expired / runtime_release_stale_link / runtime_session_ended. |
| `game_access_denied` | `auth` | no | yes | You don't have access | Ask the creator for access to this game. | Principal is not authorized for this game/room (private room, ban, missing grant, wrong player session). |
| `runtime_schema_violation` | `schema_violation` | no | yes | Game couldn't load | The game sent an update this app couldn't read. Refresh and try again. | Malformed client frame: ZodError from RuntimeClientEnvelopeSchema.parse or an otherwise unparseable envelope. |
| `runtime_identity_mismatch` | `schema_violation` | no | yes | Game couldn't load | Refresh and try again. | Runtime envelope identity mismatch: a supplied room, player session or deployment coordinate differs from the authenticated connection. |
| `game_connection_payload_too_large` | `schema_violation` | no | yes | Game couldn't load | The game sent too much data. Refresh and try again. | Inbound envelope exceeds RUNTIME_GATEWAY_POLICY.maxEnvelopeBytes. |
| `runtime_protocol_unsupported` | `release_mismatch` | no | yes | Update to keep playing | This game connection is out of date. Refresh and try again. | Client protocol version does not equal server RUNTIME_PROTOCOL_VERSION. |
| `runtime_engine_contract` | `release_mismatch` | no | yes | Game version not supported | This game version is not supported yet. Refresh and try again. | Engine-contract mismatch. Code is a prefix family: runtime_engine_contract_<suffix>. |
| `runtime_admission_missing` | `release_mismatch` | no | yes | Game unavailable | This game has no published release for this environment yet. Try again soon. | Versioned admission: no versioned release for the requested environment (VersioningV1Error). |
| `runtime_admission_superseded` | `release_mismatch` | yes | yes | Update to keep playing | This game was updated to a newer version. Refresh and try again. | Versioned admission: pinned deployment was superseded by a newer release. A fresh attempt admits to the new release. |
| `runtime_target_unhealthy` | `release_mismatch` | yes | no | Getting the game ready | The game runtime is not ready yet. Try again in a moment. | Versioned admission: target deployment is not healthy yet. |
| `runtime_admission_incoherent` | `release_mismatch` | no | yes | Game needs attention | This game's release needs attention before it can start. Try again soon. | Versioned admission: the release resolved to an incoherent state and cannot start. |
| `admission_identity_required` | `auth` | yes | yes | Sign in to play | We couldn't confirm your session. Sign in to continue. | Admission policy: the principal carried no account identity; the player shell retries once through guest start before surfacing this. |
| `admission_account_required` | `auth` | no | yes | Account required | This game requires an account. Sign in or create one to play. | Admission policy: the deployment denies guest accounts and the participant is a guest account. |
| `admission_banned` | `auth` | no | yes | You can't join this game | Your account can't join this game right now. | Admission: an active ban (deployment, game or platform scope) matched the participant's account, device or network coordinates. |
| `admission_account_too_new` | `auth` | no | yes | Account too new | This game is open to established accounts. Try again once your account is a little older. | Admission policy: the account is younger than the deployment's minimum account age. |
| `runtime_room_policy_invalid` | `release_mismatch` | no | yes | Game unavailable | This game is not available with those settings. Refresh and try again. | Room-creation request violated a non-capacity policy bound (tick/snapshot rate, snapshot > tick, unsupported region). |
| `runtime_protocol_epoch_unservable` | `release_mismatch` | no | yes | Game unavailable | This game is not available right now. Try again in a moment. | Room's immutable authority protocol epoch has no corridor for the requested operation. Operator/deployment invariant violation; no retry advances an immutable epoch. |
| `runtime_release_stale_link` | `release_mismatch` | no | yes | Game link is out of date | This game link points to an older version. Refresh and try again. | Credential game/room/deployment scope mismatch (verifyRuntimePlayerCredential game/room/deployment checks). Stale link, not auth fraud. |
| `game_not_found` | `release_mismatch` | no | yes | Game not found | Check the link and try again. | Requested game or deployment does not resolve (deployment not found / resource not found). |
| `runtime_snapshot_timeout` | `boot_failure` | yes | no | Game world is taking too long | The server accepted you, but the first playable world update has not arrived. | First full snapshot did not arrive within the boot deadline. Terminal only once the transport is disconnected (applied FE-side). |
| `runtime_delta_gap` | `boot_failure` | yes | no | Game world is taking too long | The server accepted you, but the first playable world update has not arrived. | A delta arrived with a sequence gap before the first playable frame. Terminal only once the transport is disconnected (applied FE-side). |
| `runtime_delta_without_snapshot` | `boot_failure` | yes | no | Game world is taking too long | The server accepted you, but the first playable world update has not arrived. | A delta arrived before any baseline snapshot. Terminal only once the transport is disconnected (applied FE-side). |
| `runtime_resync_failed` | `boot_failure` | no | yes | Game couldn't load | Refresh and try again. | Warm-resume resync failed to weld to the replay window. |
| `runtime_play_session_timeout` | `boot_failure` | no | yes | Game couldn't load | Refresh and try again. | Play-session boot exceeded its deadline. |
| `runtime_play_session_failed` | `boot_failure` | no | yes | Game couldn't load | Refresh and try again. | Play-session boot failed terminally. |
| `rejected_terminal_policy` | `boot_failure` | no | yes | Game couldn't load | Refresh and try again. | Admission rejected under a terminal policy: no retry can satisfy it. |
| `game_admission_blocked` | `boot_failure` | no | yes | Game needs an update | This game needs an update before it can start. Try again soon. | Content admission gate (e.g. a ProjectAsset lineage receipt / backfill) blocks any session start until the game's stored content is updated. |
| `game_content_not_publishable` | `boot_failure` | no | yes | Game couldn't load | One of this game's assets isn't stored durably yet. Re-import the asset or finish its upload, then try again. | Immutable publication refused the content-version mint: a runtime asset variant lacks immutable byte identity (versionless s3 reference, null object version, or identity disagreement). The server log names the asset and variant. |
| `runtime_compute_unavailable` | `overload` | yes | no | Game is busy | The game is getting ready. Please try again in a moment. | Canonical compute admission, worker failure or deadline prevented snapshot preparation. Retry the same idempotent admission; never run the snapshot on the serving loop. |
| `runtime_handshake_budget` | `overload` | yes | no | Too many attempts | The game is busy. Wait a moment and try again. | Handshake admission budget exceeded (WS 1013). Client honors retryAfterMs under the reconnect jitter. |
| `runtime_command_rate_limited` | `overload` | yes | no | Slow down | You're sending input too fast. It will catch up in a moment. | Per-connection command pressure budget exceeded (connection-scope reject). |
| `runtime_room_pressure_shedding` | `overload` | yes | no | Game is busy | The game is under heavy load and may feel choppy for a moment. | Runtime ingress or room pressure exceeded: reject before admission, resumably close an overloaded raw socket (WS 1013), or shed low-priority room replication / use thin snapshots. |
| `runtime_shard_shedding` | `overload` | yes | no | Game is busy | The game is under heavy load and may feel choppy for a moment. | Shard-level overload ladder active (thin snapshots / reduced rate / paused non-essential lanes / joins refused). Shard-scope shed; per-room order composes underneath. |
| `game_full` | `capacity` | yes | yes | Game is full | Try again in a little while. | Room fan-out or per-room player cap exhausted. Overflow is retryable (queues in P2), so terminal-but-retryable. |
| `runtime_shard_over_budget` | `capacity` | yes | yes | Game is full | Try again in a little while. | Placement refused: per-instance or per-shard room/player budget exhausted (capacity floor, D14). A fresh attempt admits once a room closes and frees budget. |
| `game_connection_rate_limited` | `rate_limited` | yes | no | Too many attempts | Wait a moment and try again. | Connection-attempt rate limit for this principal/IP. |
| `game_connection_failed` | `transport` | yes | yes | Game couldn't load | The game connection failed. Try again. | Generic transport failure. Post-taxonomy this is rare: an UNTYPED error at the boundary maps to runtime_internal, not here. |
| `runtime_liveness_reaped` | `transport` | yes | no | Reconnecting | The game connection dropped. Reconnecting now. | Liveness ping/pong reaped a half-open socket (WS 1008 gateway_liveness_timeout). Resumable. |
| `runtime_transport_dropped` | `transport` | yes | no | Reconnecting | The game connection dropped. Reconnecting now. | Abnormal (1006) transport drop. Resumable via warm resume. |
| `runtime_reconnect_exhausted` | `transport` | no | yes | Connection lost | We couldn't reconnect to the game. Refresh and try again. | Client reconnect attempt ceiling reached (bounded + full jitter, 03 section 4). |
| `runtime_internal` | `transport` | no | yes | Game couldn't load | Something went wrong. Refresh and try again. | An UNTYPED error reached the boundary: a missing coded throw. Logs loudly (logRuntimeGatewayLaunderedFallback); it signals a bug, not an accepted fallback path. |
| `runtime_authority_recovering` | `lifecycle` | yes | no | Reconnecting | The game connection is being restored. | Owner-lease/routing transient (isRuntimeRecoverableAuthorityError). |
| `runtime_authoritative_frame_conflict` | `lifecycle` | yes | no | Reconnecting | The game connection is catching up. | Authority persistence conflict (Postgres 23505 unique violation). Reconciles forward. |
| `runtime_session_ended` | `lifecycle` | no | yes | Game session ended | This game session has ended. Refresh to start a new one. | Player session not found for credential (service.ts openGatewayConnection). Session lifecycle ended, not an auth failure. |
| `runtime_superseded` | `lifecycle` | no | yes | Playing somewhere else | You started playing in another tab or on another device. You can close this tab. | Occupancy supersede (WS 4001, reason occupancy_superseded). A newer admission of the same Account departed this seat; the process-local registry or the backplane closed the socket. FE renders 'playing elsewhere' and never reconnects; never an auth failure (docs/cycles/occupancy-law/SPEC.md S13). |
| `game_open_in_progress` | `lifecycle` | yes | yes | Game is already open | Close the other tab or refresh this one to continue. | Still-opening idempotency race (transient duplicate join). Retryable; a durable idempotency mismatch is a different, non-retryable outcome. |
| `reconnect_or_exit` | `lifecycle` | yes | no | Reconnecting | The game connection is being restored. | Lifecycle-continuable drain notice: a still-rendering game keeps drawing and rolls forward to the live deployment (INV3 active-never-fails). |
| `game_server_starting` | `lifecycle` | yes | no | Getting the game ready | The game server is getting ready. Try again in a moment. | Room owner lease is not active yet (room warming up). |
| `game_server_restarting` | `lifecycle` | yes | no | Server is restarting | Try again in a moment. | Room draining / sleeping / recovering / restarting. |
| `game_updating` | `lifecycle` | yes | no | Game is updating | Try again in a moment. | Deployment superseded by a redeploy in flight; rolls forward once the new deployment admits. |
| `game_unavailable` | `lifecycle` | yes | no | Game unavailable | Check the link or try again in a moment. | Game has no active deployment / no published world right now. |
| `runtime_session_revoked` | `revoked` | no | yes | You've been signed out | Your access to this game was ended. Sign in again to continue. | Explicit revocation, fence loss, kick, ban, or logout-everywhere (03 section 3). The only non-supersede path to instant termination. |
| `occupancy_conflict` | `lifecycle` | yes | no | Moving your session | Your session is being moved. One moment. | An occupancy invariant refused a write (a partial unique index on Postgres, the mirrored predicate on the memory twin): a second live seat for the Account, a second live seat for a Profile in one room, or a duplicate live ticket, party membership, or match participant. Retry once; the retry observes the committed state (docs/cycles/occupancy-law/SPEC.md S4.1, I-01, I-02, I-15). |
| `occupancy_client_mismatch` | `lifecycle` | no | no | Session belongs to another window | This seat is being driven from another window. Start playing here to take it over. | A socket attach for a live seat came from a client instance that is not the seat's client instance. The client admits instead, which supersedes (docs/cycles/occupancy-law/SPEC.md S4.2, I-12). |
| `admission_rate_limited` | `rate_limited` | yes | no | Slow down | Too many attempts to join. Try again in a moment. | The admission budget keyed by Account or by network denied a seat-minting request; the response carries the retry delay (docs/cycles/occupancy-law/SPEC.md S10, I-18). |
| `room_creation_rate_limited` | `rate_limited` | yes | no | Slow down | Too many attempts to join. Try again in a moment. | The room-creation budget keyed by Account or by game denied a request that would have created a room; the response carries the retry delay (docs/cycles/occupancy-law/SPEC.md S10, I-18). |
| `placement_not_client_owned` | `schema_violation` | no | yes | Update to keep playing | This game link is out of date. Refresh and try again. | A public play request carried a client placement field (room key, shard, capacity, rates, region, join policy). Public placement derives from the deployment; a client defect, never a player action (docs/cycles/occupancy-law/SPEC.md S9, I-17). |
| `identity_field_not_allowed` | `schema_violation` | no | yes | Update to keep playing | This game link is out of date. Refresh and try again. | A human or guest principal supplied an identity field (player id) on a ticket, party, or admission request. Identity derives from the principal inside the occupancy authority; a client defect (docs/cycles/occupancy-law/SPEC.md S8, I-14). |
| `runtime_request_conflict` | `schema_violation` | no | yes | Game couldn't load | Refresh and try again. | A mutation reused an idempotency key with a different request body (IdempotencyReplayConflictError). A durable mismatch, not the still-opening join race (game_open_in_progress): repeating the same request can never succeed, so it is never retryable. |
| `runtime_request_invalid` | `schema_violation` | no | yes | Game couldn't load | Refresh and try again. | A mutation arrived without its required x-idempotency-key header (runtimeRequestInvalidError). A client contract defect, not a transient state: the same request can never succeed until the client sends the header, so it is never retryable. |
| `observer_bound_exceeded` | `overload` | yes | no | Too many views open | You are already watching this room from too many places. Close one and try again. | An Account asked to observe one room past the observer bound, refused inside createObserverSession under the room lock on both twins. The bound is a policy value, not a literal (docs/cycles/occupancy-law/SPEC.md S8, I-16). |
| `occupancy_connection_not_current` | `lifecycle` | no | no | Connection replaced | Another connection is driving this session now. | The occupancy fence refused a packet or a close from a socket that is not the seat's current connection (a superseded or replaced socket). Compared against the seat row, never a message; the stale socket closes on its own typed close (docs/cycles/occupancy-law/SPEC.md S5, I-08, I-09). |

## Code details

The engine-contract family is matched by code prefix rather than an exact key; its canonical entry is keyed by the bare stem.

### runtime_auth_invalid

| Field | Value |
| --- | --- |
| Category | `auth` |
| Disposition | denied |
| Retryable | no |
| Terminal | yes |
| Player title | Sign in to play |
| Player message | We couldn't verify your game session. Refresh the page or sign in again to continue. |
| Operator description | Runtime player credential MAC/signature invalid, malformed, or an impostor token: genuine auth failure. Terminal. |
### runtime_credential_expired

| Field | Value |
| --- | --- |
| Category | `auth` |
| Disposition | denied |
| Retryable | yes |
| Terminal | no |
| Player title | Reconnecting |
| Player message | Refreshing your game session. |
| Operator description | Runtime player credential expired (expiresAtMs <= now). Sliding re-mint over the live socket (03 section 2); degraded, not terminal. |
### runtime_connection_unverified

| Field | Value |
| --- | --- |
| Category | `auth` |
| Disposition | denied |
| Retryable | yes |
| Terminal | yes |
| Player title | Sign in to play |
| Player message | Refresh the page or sign in again to continue. |
| Operator description | Legacy unverified-connection catch-all. Migrate throw sites to runtime_auth_invalid / runtime_credential_expired / runtime_release_stale_link / runtime_session_ended. |
### game_access_denied

| Field | Value |
| --- | --- |
| Category | `auth` |
| Disposition | denied |
| Retryable | no |
| Terminal | yes |
| Player title | You don't have access |
| Player message | Ask the creator for access to this game. |
| Operator description | Principal is not authorized for this game/room (private room, ban, missing grant, wrong player session). |
### runtime_schema_violation

| Field | Value |
| --- | --- |
| Category | `schema_violation` |
| Disposition | malformed |
| Retryable | no |
| Terminal | yes |
| Player title | Game couldn't load |
| Player message | The game sent an update this app couldn't read. Refresh and try again. |
| Operator description | Malformed client frame: ZodError from RuntimeClientEnvelopeSchema.parse or an otherwise unparseable envelope. |
### runtime_identity_mismatch

| Field | Value |
| --- | --- |
| Category | `schema_violation` |
| Disposition | malformed |
| Retryable | no |
| Terminal | yes |
| Player title | Game couldn't load |
| Player message | Refresh and try again. |
| Operator description | Runtime envelope identity mismatch: a supplied room, player session or deployment coordinate differs from the authenticated connection. |
### game_connection_payload_too_large

| Field | Value |
| --- | --- |
| Category | `schema_violation` |
| Disposition | malformed |
| Retryable | no |
| Terminal | yes |
| Player title | Game couldn't load |
| Player message | The game sent too much data. Refresh and try again. |
| Operator description | Inbound envelope exceeds RUNTIME_GATEWAY_POLICY.maxEnvelopeBytes. |
### runtime_protocol_unsupported

| Field | Value |
| --- | --- |
| Category | `release_mismatch` |
| Disposition | stale_release |
| Retryable | no |
| Terminal | yes |
| Player title | Update to keep playing |
| Player message | This game connection is out of date. Refresh and try again. |
| Operator description | Client protocol version does not equal server RUNTIME_PROTOCOL_VERSION. |
### runtime_engine_contract

| Field | Value |
| --- | --- |
| Category | `release_mismatch` |
| Code family | prefix `runtime_engine_contract_` |
| Disposition | stale_release |
| Retryable | no |
| Terminal | yes |
| Player title | Game version not supported |
| Player message | This game version is not supported yet. Refresh and try again. |
| Operator description | Engine-contract mismatch. Code is a prefix family: runtime_engine_contract_<suffix>. |
### runtime_admission_missing

| Field | Value |
| --- | --- |
| Category | `release_mismatch` |
| Disposition | stale_release |
| Retryable | no |
| Terminal | yes |
| Player title | Game unavailable |
| Player message | This game has no published release for this environment yet. Try again soon. |
| Operator description | Versioned admission: no versioned release for the requested environment (VersioningV1Error). |
### runtime_admission_superseded

| Field | Value |
| --- | --- |
| Category | `release_mismatch` |
| Disposition | stale_release |
| Retryable | yes |
| Terminal | yes |
| Player title | Update to keep playing |
| Player message | This game was updated to a newer version. Refresh and try again. |
| Operator description | Versioned admission: pinned deployment was superseded by a newer release. A fresh attempt admits to the new release. |
### runtime_target_unhealthy

| Field | Value |
| --- | --- |
| Category | `release_mismatch` |
| Disposition | stale_release |
| Retryable | yes |
| Terminal | no |
| Player title | Getting the game ready |
| Player message | The game runtime is not ready yet. Try again in a moment. |
| Operator description | Versioned admission: target deployment is not healthy yet. |
### runtime_admission_incoherent

| Field | Value |
| --- | --- |
| Category | `release_mismatch` |
| Disposition | stale_release |
| Retryable | no |
| Terminal | yes |
| Player title | Game needs attention |
| Player message | This game's release needs attention before it can start. Try again soon. |
| Operator description | Versioned admission: the release resolved to an incoherent state and cannot start. |
### admission_identity_required

| Field | Value |
| --- | --- |
| Category | `auth` |
| Disposition | denied |
| Retryable | yes |
| Terminal | yes |
| Player title | Sign in to play |
| Player message | We couldn't confirm your session. Sign in to continue. |
| Operator description | Admission policy: the principal carried no account identity; the player shell retries once through guest start before surfacing this. |
### admission_account_required

| Field | Value |
| --- | --- |
| Category | `auth` |
| Disposition | denied |
| Retryable | no |
| Terminal | yes |
| Player title | Account required |
| Player message | This game requires an account. Sign in or create one to play. |
| Operator description | Admission policy: the deployment denies guest accounts and the participant is a guest account. |
### admission_banned

| Field | Value |
| --- | --- |
| Category | `auth` |
| Disposition | denied |
| Retryable | no |
| Terminal | yes |
| Player title | You can't join this game |
| Player message | Your account can't join this game right now. |
| Operator description | Admission: an active ban (deployment, game or platform scope) matched the participant's account, device or network coordinates. |
### admission_account_too_new

| Field | Value |
| --- | --- |
| Category | `auth` |
| Disposition | denied |
| Retryable | no |
| Terminal | yes |
| Player title | Account too new |
| Player message | This game is open to established accounts. Try again once your account is a little older. |
| Operator description | Admission policy: the account is younger than the deployment's minimum account age. |
### runtime_room_policy_invalid

| Field | Value |
| --- | --- |
| Category | `release_mismatch` |
| Disposition | stale_release |
| Retryable | no |
| Terminal | yes |
| Player title | Game unavailable |
| Player message | This game is not available with those settings. Refresh and try again. |
| Operator description | Room-creation request violated a non-capacity policy bound (tick/snapshot rate, snapshot > tick, unsupported region). |
### runtime_protocol_epoch_unservable

| Field | Value |
| --- | --- |
| Category | `release_mismatch` |
| Disposition | stale_release |
| Retryable | no |
| Terminal | yes |
| Player title | Game unavailable |
| Player message | This game is not available right now. Try again in a moment. |
| Operator description | Room's immutable authority protocol epoch has no corridor for the requested operation. Operator/deployment invariant violation; no retry advances an immutable epoch. |
### runtime_release_stale_link

| Field | Value |
| --- | --- |
| Category | `release_mismatch` |
| Disposition | stale_release |
| Retryable | no |
| Terminal | yes |
| Player title | Game link is out of date |
| Player message | This game link points to an older version. Refresh and try again. |
| Operator description | Credential game/room/deployment scope mismatch (verifyRuntimePlayerCredential game/room/deployment checks). Stale link, not auth fraud. |
### game_not_found

| Field | Value |
| --- | --- |
| Category | `release_mismatch` |
| Disposition | stale_release |
| Retryable | no |
| Terminal | yes |
| Player title | Game not found |
| Player message | Check the link and try again. |
| Operator description | Requested game or deployment does not resolve (deployment not found / resource not found). |
### runtime_snapshot_timeout

| Field | Value |
| --- | --- |
| Category | `boot_failure` |
| Disposition | booting |
| Retryable | yes |
| Terminal | no |
| Player title | Game world is taking too long |
| Player message | The server accepted you, but the first playable world update has not arrived. |
| Operator description | First full snapshot did not arrive within the boot deadline. Terminal only once the transport is disconnected (applied FE-side). |
### runtime_delta_gap

| Field | Value |
| --- | --- |
| Category | `boot_failure` |
| Disposition | booting |
| Retryable | yes |
| Terminal | no |
| Player title | Game world is taking too long |
| Player message | The server accepted you, but the first playable world update has not arrived. |
| Operator description | A delta arrived with a sequence gap before the first playable frame. Terminal only once the transport is disconnected (applied FE-side). |
### runtime_delta_without_snapshot

| Field | Value |
| --- | --- |
| Category | `boot_failure` |
| Disposition | booting |
| Retryable | yes |
| Terminal | no |
| Player title | Game world is taking too long |
| Player message | The server accepted you, but the first playable world update has not arrived. |
| Operator description | A delta arrived before any baseline snapshot. Terminal only once the transport is disconnected (applied FE-side). |
### runtime_resync_failed

| Field | Value |
| --- | --- |
| Category | `boot_failure` |
| Disposition | booting |
| Retryable | no |
| Terminal | yes |
| Player title | Game couldn't load |
| Player message | Refresh and try again. |
| Operator description | Warm-resume resync failed to weld to the replay window. |
### runtime_play_session_timeout

| Field | Value |
| --- | --- |
| Category | `boot_failure` |
| Disposition | booting |
| Retryable | no |
| Terminal | yes |
| Player title | Game couldn't load |
| Player message | Refresh and try again. |
| Operator description | Play-session boot exceeded its deadline. |
### runtime_play_session_failed

| Field | Value |
| --- | --- |
| Category | `boot_failure` |
| Disposition | booting |
| Retryable | no |
| Terminal | yes |
| Player title | Game couldn't load |
| Player message | Refresh and try again. |
| Operator description | Play-session boot failed terminally. |
### rejected_terminal_policy

| Field | Value |
| --- | --- |
| Category | `boot_failure` |
| Disposition | booting |
| Retryable | no |
| Terminal | yes |
| Player title | Game couldn't load |
| Player message | Refresh and try again. |
| Operator description | Admission rejected under a terminal policy: no retry can satisfy it. |
### game_admission_blocked

| Field | Value |
| --- | --- |
| Category | `boot_failure` |
| Disposition | booting |
| Retryable | no |
| Terminal | yes |
| Player title | Game needs an update |
| Player message | This game needs an update before it can start. Try again soon. |
| Operator description | Content admission gate (e.g. a ProjectAsset lineage receipt / backfill) blocks any session start until the game's stored content is updated. |
### game_content_not_publishable

| Field | Value |
| --- | --- |
| Category | `boot_failure` |
| Disposition | booting |
| Retryable | no |
| Terminal | yes |
| Player title | Game couldn't load |
| Player message | One of this game's assets isn't stored durably yet. Re-import the asset or finish its upload, then try again. |
| Operator description | Immutable publication refused the content-version mint: a runtime asset variant lacks immutable byte identity (versionless s3 reference, null object version, or identity disagreement). The server log names the asset and variant. |
### runtime_compute_unavailable

| Field | Value |
| --- | --- |
| Category | `overload` |
| Disposition | shedding |
| Retryable | yes |
| Terminal | no |
| Player title | Game is busy |
| Player message | The game is getting ready. Please try again in a moment. |
| Operator description | Canonical compute admission, worker failure or deadline prevented snapshot preparation. Retry the same idempotent admission; never run the snapshot on the serving loop. |
### runtime_handshake_budget

| Field | Value |
| --- | --- |
| Category | `overload` |
| Disposition | shedding |
| Retryable | yes |
| Terminal | no |
| Player title | Too many attempts |
| Player message | The game is busy. Wait a moment and try again. |
| Operator description | Handshake admission budget exceeded (WS 1013). Client honors retryAfterMs under the reconnect jitter. |
### runtime_command_rate_limited

| Field | Value |
| --- | --- |
| Category | `overload` |
| Disposition | shedding |
| Retryable | yes |
| Terminal | no |
| Player title | Slow down |
| Player message | You're sending input too fast. It will catch up in a moment. |
| Operator description | Per-connection command pressure budget exceeded (connection-scope reject). |
### runtime_room_pressure_shedding

| Field | Value |
| --- | --- |
| Category | `overload` |
| Disposition | shedding |
| Retryable | yes |
| Terminal | no |
| Player title | Game is busy |
| Player message | The game is under heavy load and may feel choppy for a moment. |
| Operator description | Runtime ingress or room pressure exceeded: reject before admission, resumably close an overloaded raw socket (WS 1013), or shed low-priority room replication / use thin snapshots. |
### runtime_shard_shedding

| Field | Value |
| --- | --- |
| Category | `overload` |
| Disposition | shedding |
| Retryable | yes |
| Terminal | no |
| Player title | Game is busy |
| Player message | The game is under heavy load and may feel choppy for a moment. |
| Operator description | Shard-level overload ladder active (thin snapshots / reduced rate / paused non-essential lanes / joins refused). Shard-scope shed; per-room order composes underneath. |
### game_full

| Field | Value |
| --- | --- |
| Category | `capacity` |
| Disposition | at_capacity |
| Retryable | yes |
| Terminal | yes |
| Player title | Game is full |
| Player message | Try again in a little while. |
| Operator description | Room fan-out or per-room player cap exhausted. Overflow is retryable (queues in P2), so terminal-but-retryable. |
### runtime_shard_over_budget

| Field | Value |
| --- | --- |
| Category | `capacity` |
| Disposition | at_capacity |
| Retryable | yes |
| Terminal | yes |
| Player title | Game is full |
| Player message | Try again in a little while. |
| Operator description | Placement refused: per-instance or per-shard room/player budget exhausted (capacity floor, D14). A fresh attempt admits once a room closes and frees budget. |
### game_connection_rate_limited

| Field | Value |
| --- | --- |
| Category | `rate_limited` |
| Disposition | throttled |
| Retryable | yes |
| Terminal | no |
| Player title | Too many attempts |
| Player message | Wait a moment and try again. |
| Operator description | Connection-attempt rate limit for this principal/IP. |
### game_connection_failed

| Field | Value |
| --- | --- |
| Category | `transport` |
| Disposition | transport |
| Retryable | yes |
| Terminal | yes |
| Player title | Game couldn't load |
| Player message | The game connection failed. Try again. |
| Operator description | Generic transport failure. Post-taxonomy this is rare: an UNTYPED error at the boundary maps to runtime_internal, not here. |
### runtime_liveness_reaped

| Field | Value |
| --- | --- |
| Category | `transport` |
| Disposition | transport |
| Retryable | yes |
| Terminal | no |
| Player title | Reconnecting |
| Player message | The game connection dropped. Reconnecting now. |
| Operator description | Liveness ping/pong reaped a half-open socket (WS 1008 gateway_liveness_timeout). Resumable. |
### runtime_transport_dropped

| Field | Value |
| --- | --- |
| Category | `transport` |
| Disposition | transport |
| Retryable | yes |
| Terminal | no |
| Player title | Reconnecting |
| Player message | The game connection dropped. Reconnecting now. |
| Operator description | Abnormal (1006) transport drop. Resumable via warm resume. |
### runtime_reconnect_exhausted

| Field | Value |
| --- | --- |
| Category | `transport` |
| Disposition | transport |
| Retryable | no |
| Terminal | yes |
| Player title | Connection lost |
| Player message | We couldn't reconnect to the game. Refresh and try again. |
| Operator description | Client reconnect attempt ceiling reached (bounded + full jitter, 03 section 4). |
### runtime_internal

| Field | Value |
| --- | --- |
| Category | `transport` |
| Disposition | transport |
| Retryable | no |
| Terminal | yes |
| Player title | Game couldn't load |
| Player message | Something went wrong. Refresh and try again. |
| Operator description | An UNTYPED error reached the boundary: a missing coded throw. Logs loudly (logRuntimeGatewayLaunderedFallback); it signals a bug, not an accepted fallback path. |
### runtime_authority_recovering

| Field | Value |
| --- | --- |
| Category | `lifecycle` |
| Disposition | lifecycle |
| Retryable | yes |
| Terminal | no |
| Player title | Reconnecting |
| Player message | The game connection is being restored. |
| Operator description | Owner-lease/routing transient (isRuntimeRecoverableAuthorityError). |
### runtime_authoritative_frame_conflict

| Field | Value |
| --- | --- |
| Category | `lifecycle` |
| Disposition | lifecycle |
| Retryable | yes |
| Terminal | no |
| Player title | Reconnecting |
| Player message | The game connection is catching up. |
| Operator description | Authority persistence conflict (Postgres 23505 unique violation). Reconciles forward. |
### runtime_session_ended

| Field | Value |
| --- | --- |
| Category | `lifecycle` |
| Disposition | lifecycle |
| Retryable | no |
| Terminal | yes |
| Player title | Game session ended |
| Player message | This game session has ended. Refresh to start a new one. |
| Operator description | Player session not found for credential (service.ts openGatewayConnection). Session lifecycle ended, not an auth failure. |
### runtime_superseded

| Field | Value |
| --- | --- |
| Category | `lifecycle` |
| Disposition | lifecycle |
| Retryable | no |
| Terminal | yes |
| Player title | Playing somewhere else |
| Player message | You started playing in another tab or on another device. You can close this tab. |
| Operator description | Occupancy supersede (WS 4001, reason occupancy_superseded). A newer admission of the same Account departed this seat; the process-local registry or the backplane closed the socket. FE renders 'playing elsewhere' and never reconnects; never an auth failure (docs/cycles/occupancy-law/SPEC.md S13). |
### game_open_in_progress

| Field | Value |
| --- | --- |
| Category | `lifecycle` |
| Disposition | lifecycle |
| Retryable | yes |
| Terminal | yes |
| Player title | Game is already open |
| Player message | Close the other tab or refresh this one to continue. |
| Operator description | Still-opening idempotency race (transient duplicate join). Retryable; a durable idempotency mismatch is a different, non-retryable outcome. |
### reconnect_or_exit

| Field | Value |
| --- | --- |
| Category | `lifecycle` |
| Disposition | lifecycle |
| Retryable | yes |
| Terminal | no |
| Player title | Reconnecting |
| Player message | The game connection is being restored. |
| Operator description | Lifecycle-continuable drain notice: a still-rendering game keeps drawing and rolls forward to the live deployment (INV3 active-never-fails). |
### game_server_starting

| Field | Value |
| --- | --- |
| Category | `lifecycle` |
| Disposition | lifecycle |
| Retryable | yes |
| Terminal | no |
| Player title | Getting the game ready |
| Player message | The game server is getting ready. Try again in a moment. |
| Operator description | Room owner lease is not active yet (room warming up). |
### game_server_restarting

| Field | Value |
| --- | --- |
| Category | `lifecycle` |
| Disposition | lifecycle |
| Retryable | yes |
| Terminal | no |
| Player title | Server is restarting |
| Player message | Try again in a moment. |
| Operator description | Room draining / sleeping / recovering / restarting. |
### game_updating

| Field | Value |
| --- | --- |
| Category | `lifecycle` |
| Disposition | lifecycle |
| Retryable | yes |
| Terminal | no |
| Player title | Game is updating |
| Player message | Try again in a moment. |
| Operator description | Deployment superseded by a redeploy in flight; rolls forward once the new deployment admits. |
### game_unavailable

| Field | Value |
| --- | --- |
| Category | `lifecycle` |
| Disposition | lifecycle |
| Retryable | yes |
| Terminal | no |
| Player title | Game unavailable |
| Player message | Check the link or try again in a moment. |
| Operator description | Game has no active deployment / no published world right now. |
### runtime_session_revoked

| Field | Value |
| --- | --- |
| Category | `revoked` |
| Disposition | revoked |
| Retryable | no |
| Terminal | yes |
| Player title | You've been signed out |
| Player message | Your access to this game was ended. Sign in again to continue. |
| Operator description | Explicit revocation, fence loss, kick, ban, or logout-everywhere (03 section 3). The only non-supersede path to instant termination. |
### occupancy_conflict

| Field | Value |
| --- | --- |
| Category | `lifecycle` |
| Disposition | lifecycle |
| Retryable | yes |
| Terminal | no |
| Player title | Moving your session |
| Player message | Your session is being moved. One moment. |
| Operator description | An occupancy invariant refused a write (a partial unique index on Postgres, the mirrored predicate on the memory twin): a second live seat for the Account, a second live seat for a Profile in one room, or a duplicate live ticket, party membership, or match participant. Retry once; the retry observes the committed state (docs/cycles/occupancy-law/SPEC.md S4.1, I-01, I-02, I-15). |
### occupancy_client_mismatch

| Field | Value |
| --- | --- |
| Category | `lifecycle` |
| Disposition | lifecycle |
| Retryable | no |
| Terminal | no |
| Player title | Session belongs to another window |
| Player message | This seat is being driven from another window. Start playing here to take it over. |
| Operator description | A socket attach for a live seat came from a client instance that is not the seat's client instance. The client admits instead, which supersedes (docs/cycles/occupancy-law/SPEC.md S4.2, I-12). |
### admission_rate_limited

| Field | Value |
| --- | --- |
| Category | `rate_limited` |
| Disposition | throttled |
| Retryable | yes |
| Terminal | no |
| Player title | Slow down |
| Player message | Too many attempts to join. Try again in a moment. |
| Operator description | The admission budget keyed by Account or by network denied a seat-minting request; the response carries the retry delay (docs/cycles/occupancy-law/SPEC.md S10, I-18). |
### room_creation_rate_limited

| Field | Value |
| --- | --- |
| Category | `rate_limited` |
| Disposition | throttled |
| Retryable | yes |
| Terminal | no |
| Player title | Slow down |
| Player message | Too many attempts to join. Try again in a moment. |
| Operator description | The room-creation budget keyed by Account or by game denied a request that would have created a room; the response carries the retry delay (docs/cycles/occupancy-law/SPEC.md S10, I-18). |
### placement_not_client_owned

| Field | Value |
| --- | --- |
| Category | `schema_violation` |
| Disposition | malformed |
| Retryable | no |
| Terminal | yes |
| Player title | Update to keep playing |
| Player message | This game link is out of date. Refresh and try again. |
| Operator description | A public play request carried a client placement field (room key, shard, capacity, rates, region, join policy). Public placement derives from the deployment; a client defect, never a player action (docs/cycles/occupancy-law/SPEC.md S9, I-17). |
### identity_field_not_allowed

| Field | Value |
| --- | --- |
| Category | `schema_violation` |
| Disposition | malformed |
| Retryable | no |
| Terminal | yes |
| Player title | Update to keep playing |
| Player message | This game link is out of date. Refresh and try again. |
| Operator description | A human or guest principal supplied an identity field (player id) on a ticket, party, or admission request. Identity derives from the principal inside the occupancy authority; a client defect (docs/cycles/occupancy-law/SPEC.md S8, I-14). |
### runtime_request_conflict

| Field | Value |
| --- | --- |
| Category | `schema_violation` |
| Disposition | malformed |
| Retryable | no |
| Terminal | yes |
| Player title | Game couldn't load |
| Player message | Refresh and try again. |
| Operator description | A mutation reused an idempotency key with a different request body (IdempotencyReplayConflictError). A durable mismatch, not the still-opening join race (game_open_in_progress): repeating the same request can never succeed, so it is never retryable. |
### runtime_request_invalid

| Field | Value |
| --- | --- |
| Category | `schema_violation` |
| Disposition | malformed |
| Retryable | no |
| Terminal | yes |
| Player title | Game couldn't load |
| Player message | Refresh and try again. |
| Operator description | A mutation arrived without its required x-idempotency-key header (runtimeRequestInvalidError). A client contract defect, not a transient state: the same request can never succeed until the client sends the header, so it is never retryable. |
### observer_bound_exceeded

| Field | Value |
| --- | --- |
| Category | `overload` |
| Disposition | shedding |
| Retryable | yes |
| Terminal | no |
| Player title | Too many views open |
| Player message | You are already watching this room from too many places. Close one and try again. |
| Operator description | An Account asked to observe one room past the observer bound, refused inside createObserverSession under the room lock on both twins. The bound is a policy value, not a literal (docs/cycles/occupancy-law/SPEC.md S8, I-16). |
### occupancy_connection_not_current

| Field | Value |
| --- | --- |
| Category | `lifecycle` |
| Disposition | lifecycle |
| Retryable | no |
| Terminal | no |
| Player title | Connection replaced |
| Player message | Another connection is driving this session now. |
| Operator description | The occupancy fence refused a packet or a close from a socket that is not the seat's current connection (a superseded or replaced socket). Compared against the seat row, never a message; the stale socket closes on its own typed close (docs/cycles/occupancy-law/SPEC.md S5, I-08, I-09). |