Errors and Disconnects

How Errors Are Reported

Errors reach your code through three channels. Failures of an operation you started arrive as the Err state of that operation's Result, this is where expected failures such as a full room land. Errors that occur outside any pending operation are broadcast through OnError(ErrorCode, message). Loss of the connection itself is reported through OnDisconnected(DisconnectCause).

Every failure is described by an Error value. Code is the machine-readable ErrorCode your logic branches on; Message is a human-readable UTF-8 string meant for logs and diagnostics, not for parsing.

The standard handling shape: check the result, branch on the code, log the message.

C++

Result<MutableRoomView> joined = co_await client.JoinRoom(PHOTON_STR("battle-01"));

if (joined.IsErr())
{
    switch (joined.GetErrorCode())
    {
    case ErrorCode::RoomNotFound:
        // fall back to creating the room
        break;
    case ErrorCode::RoomFull:
        // tell the player and return to matchmaking
        break;
    default:
        std::printf("join failed: %s\n",
                    reinterpret_cast<const char*>(joined.GetError().Message.c_str()));
        break;
    }
}

Error Codes

ErrorCode values are grouped by area: connection (ConnectionFailed, Timeout, ...), authentication (InvalidAuthentication, MaxCCUReached, ...), room and matchmaking (RoomFull, NoMatchFound, ...), operation limits (OperationDenied, RateLimited, ...), server (InternalServerError, PluginError, ...), client state (NotConnected, NotInRoom, InvalidState) and events (EventSizeMismatch, EventEncodeFailed, EventDecodeFailed, EventPayloadTypeMismatch). The complete list lives in the enums reference.

InvalidState deserves special attention: it means the operation was called in a state where it cannot work, Connect() while already connected, room operations while not in a room. It signals a call-ordering bug on your side rather than a network problem, so treat it as a defect to fix, not an error to retry.

Handling Disconnects

Distinguish deliberate from unexpected disconnects. A Disconnect() you issue resolves its own Task, so its completion is the natural place to react. Unexpected drops, timeouts, server-side closes, fire OnDisconnected(DisconnectCause), and GetDisconnectCause() retains the last cause for post-mortem checks.

A handler separating transient timeouts from server-initiated closes.

C++

RealtimeCore::Common::ScopedSubscription onDisconnected = client.OnDisconnected.Subscribe(
    [](DisconnectCause cause) {
        switch (cause)
        {
        case DisconnectCause::TimeoutDisconnect:
        case DisconnectCause::Exception:
            // transient: try to restore the session
            break;
        case DisconnectCause::DisconnectByServer:
        case DisconnectCause::DisconnectByServerLogic:
            // server-initiated: inform the player before retrying
            break;
        default:
            // configuration or version problems: do not auto-retry
            break;
        }
    });

Warnings

OnWarning(int warningCode) reports non-fatal conditions the SDK noticed. Treat warnings as log-worthy signals: record them with enough context to correlate against later problems, but do not build control flow on them.

Recovery Patterns

The primary recovery tool is Reconnect(). Called from the Disconnected state, it re-establishes the previous session and rejoins the room the client was last in, provided the room was created with a PlayerTtlMs large enough that the player's slot is still reserved. See Connection and Regions for the reconnect semantics and rejoin preconditions.

When Reconnect() is not enough, escalate step by step. Try Reconnect() first; if it fails, make a fresh Connect() followed by JoinRoom with Rejoin = true; if the room or the player slot is gone, re-enter matchmaking from scratch.

A recovery flow with OrElse falling back from Reconnect() to a full connect-and-rejoin.

C++

Task<Result<void>> ConnectAndRejoin(RealtimeClient& client, RealtimeCore::Common::StringType roomName)
{
    Result<void> connected = co_await client.Connect();
    if (connected.IsErr())
    {
        co_return connected;
    }

    JoinRoomOptions options;
    options.Rejoin = true;
    Result<MutableRoomView> joined = co_await client.JoinRoom(roomName, options);
    co_return joined.IsOk() ? Result<void>::Ok() : Result<void>::Err(joined.GetError());
}

Task<Result<void>> RecoverSession(RealtimeClient& client, RealtimeCore::Common::StringType roomName)
{
    return client.Reconnect()
        .OrElse([&client, roomName](const Error&) { return ConnectAndRejoin(client, roomName); });
}

For failures that are expected within a flow, a full room during matchmaking, a name collision when creating, prefer recovering in place with OrElse inside the operation chain over out-of-band retry loops. See Asynchronous Operations for the combinators.