Skip to main content

RealtimeConnectionEvent

Realtime lifecycle event delivered on the udpNotifications subscription. It is a control frame — it carries no appId, so it is never dropped by the per-app fan-out filter. Branch on code; use retryable to decide whether retrying can succeed. Most codes report that a session could not be opened or correctly scoped and are TERMINAL: the subscription completes immediately after emitting one, so the client must fix the cause and resubscribe. The exception is SERVER_DRAINING, which arrives mid-stream on a healthy subscription and does NOT end it — see that code below.

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

Fields​

RealtimeConnectionEvent.status ● String! non-null scalar​

Lifecycle status: "failed" when the session could not be established or had to be torn down, or "draining" for the one advisory case (SERVER_DRAINING) where the stream stays open.

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. SERVER_DRAINING — this API instance is being taken out of service; the stream KEEPS WORKING, but you should re-run discovery (gameClientBootstrap or mintAppToken) and move your HTTP calls and your socket together to the instance it returns before this one stops. Reaches every client of the instance, including one behind the load balancer: a draining instance stops naming itself in discovery and expires the affinity cookie the balancer set, so the move lands elsewhere.

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