Skip to main content

RealtimeConnectionEvent

Realtime lifecycle/error event delivered on the udpNotifications subscription when a session cannot be opened or correctly scoped. It is a control frame — it carries no appId, so it is never dropped by the per-app fan-out filter — and it is terminal: the subscription completes immediately after emitting it, so the client must fix the cause and resubscribe. Branch on code; use retryable to decide whether retrying can succeed. A healthy subscription never emits this type; it yields game-server notifications/responses instead.

type RealtimeConnectionEvent {
  status: String!
  code: String!
  message: String!
  retryable: Boolean!
}

Fields​

RealtimeConnectionEvent.status ● String! non-null scalar​

Lifecycle status of the session attempt. Currently always "failed" — this event is only emitted when udpNotifications could not establish (or had to tear down) the underlying UDP proxy session.

RealtimeConnectionEvent.code ● String! non-null scalar​

Machine-readable failure reason. Branch on this (not on message). Known values: AUTH_REQUIRED — no valid bearer game token was presented on the WS connection_init / request; authenticate via the Management API and resubscribe (not retryable as-is). APP_ID_REQUIRED — the subscription was opened without an appId scope; udpNotifications must be app-scoped (game tokens are app-agnostic and one socket is shared across apps), so pass the app you are playing and resubscribe (not retryable as-is). UDP_PROXY_CONNECTION_FAILED — the proxy could not open or keep a UDP socket to the selected game server (transient/infrastructure); back off and resubscribe (retryable). message carries the specific underlying detail for this case.

RealtimeConnectionEvent.message ● String! non-null scalar​

Human-readable explanation of the failure, suitable for logs and developer-facing surfaces. Do not parse or branch on this text — branch on code instead.

RealtimeConnectionEvent.retryable ● Boolean! non-null scalar​

Whether resubscribing without changing anything may succeed. true for transient failures (e.g. UDP_PROXY_CONNECTION_FAILED) — back off and retry. false for caller errors that must be fixed first (AUTH_REQUIRED needs a fresh/valid game token; APP_ID_REQUIRED needs an appId-scoped subscription).

Implemented By​

UdpNotification union