Timeouts and Removals

Not every ticket becomes a match. Two outcomes report that a player left the pool without one, and both mean the same thing for the game backend: that player is no longer matchmaking, and the backend either informs them or re-queues them.

Search timeout

A ticket that never matches expires on its own.

sequenceDiagram
    autonumber
    actor P as Player
    participant GB as Game Backend
    participant IM as IVK Match

    GB->>IM: CreateTicket(...)
    Note over IM: No compatible opponents found within<br/>pool.tickets.expiration_ttl_secs
    IM->>IM: cleanup pass evicts the ticket
    IM->>GB: outcome: ticket.expired { ticket_ids: [...] }
    GB-->>P: search timed out, retry / widen filters?

expiration_ttl_secs is effectively the maximum time a player can sit in a queue. Set it a little above the longest wait the game is willing to display, so the timeout the player sees is set by the game rather than by the matchmaker.

ticket.expired is batched: one outcome can carry many ticket IDs. Handle it as a list, not a single ticket; a handler that assumes one ticket drops players whenever a sweep expires several at once.

Removals

ticket.removed means the ticket was taken out of the pool by something other than time. The reason indicates the cause and the expected response:

Reason	Cause	What to do
QUEUE_CONFIG_CHANGED	The queue’s configuration changed incompatibly	Re-queue the player
RULESET_PARAMS_CHANGED	Engine params were reloaded and stranded the ticket	Re-queue the player
QUEUE_RETIRED	The queue was retired	Stop routing to this queue; route elsewhere or show maintenance
CLEAR_COMMAND	The queue’s pool was cleared	Re-queue the player

Most of these are recoverable without the player noticing, so re-queue rather than surfacing an error wherever possible. A queue parameter change does not need to reach the player as “matchmaking failed”.

QUEUE_RETIRED is the exception: the queue is going away, so re-queueing into it will fail with FAILED_PRECONDITION.

Orphaned tickets

ticket.orphaned is rarer: the ticket referenced a ruleset that was removed while it was waiting. Treat it exactly like a removal and re-queue the player against a ruleset that still exists.

Both outcomes are terminal

Once either is received, the ticket is gone. There is nothing to cancel and nothing to wait for. Reactivation does not apply here. It exists only for tickets that were resolved into a match that could not be honoured, which is a different case.

The full outcome list is in Matchmaking API § Outcome schema.