Gateway Close Code • AI Agent SDK

GatewayCloseCode: Structured, machine-readable reasons for a server-initiated close.

GatewayCloseCode

Defined in the protocols module.

Structured, machine-readable reasons for a server-initiated close.

Distinct from :class:ConnectErrorCode (which describes why a connection was rejected at/handshake time), these describe why an already-established connection is being torn down by the server mid-session.

Codes: SLOW_CONSUMER: The client’s outbound buffer exceeded the gateway’s advertised `max_buffered_bytes policy (a genuinely slow/stalled consumer). The server evicts it so its backlog cannot grow without bound or stall delivery to healthy clients. CREDENTIALS_ROTATED: The shared gateway secret this session authenticated under is no longer the active secret (an operator rotated auth_token and hot-reloaded, or otherwise revoked it). The server force-closes every session stamped with a stale secret so a leaked/revoked credential stops working within one reload cycle, without a full process restart. Clients should re-authenticate (see :attr:ConnectRecoveryStep.REAUTHENTICATE) and reconnect with fresh credentials rather than backing off as if the server were down. LIVENESS_TIMEOUT: The connection missed too many application-level heartbeats (see :class:LivenessPolicy): its last_activity exceeded interval_ms × missed_beats_before_reap`, so the server treats it as a dead/half-open peer and reaps it, releasing the session/presence/queue state deterministically. Half-open sockets behind NAT/proxies/mobile networks — where the peer has vanished but no FIN/RST ever arrives — are the motivating case. Clients should reconnect (their own watchdog typically force-reconnects first) rather than treating this as a fatal error.

Source

Related Documentation