Timeouts and Removals

Not every ticket becomes a match. Two outcomes tell you a player left the pool without one, and both mean the same thing for your backend: that player is no longer matchmaking, and you have to either tell them or re-queue them.

Search timeout

A ticket that never matches expires on its own.

sequenceDiagram
    autonumber
    actor P as Player
    participant GB as Your 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 your game is willing to display, so the timeout the player sees is your decision rather than a surprise from the matchmaker.

ticket.expired is batched: one outcome can carry many ticket IDs. Handle it as a list, not a single ticket, or you will drop 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 tells you whether it is the player’s problem or yours:

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 your game can. There is no reason a player should see “matchmaking failed” because you edited a queue parameter.

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 you receive either, 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 you could not honour, which is a different case.

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