Limits and guarantees
Request limits, retention windows, and matching guarantees to account for when designing a matchmaking integration.
These limits describe the service and SDK contract for SDK 0.4.0. They are not a hosted-service capacity commitment or an availability SLA.
Request and input limits
| Item | Limit or behavior |
|---|---|
| Progress batch | 1–100 actions per request. |
| Player ID | At most 32 UTF-16 code units; SDK requires 1–32. |
| SDK party | At least one player with no duplicate IDs within the party. |
| Environment key | 1–32 lowercase ASCII letters, digits, underscores, or hyphens; starts with a letter. |
| Configured environments | 1–20 unique keys per deployment. |
| SDK heartbeat | Defaults to 5 seconds; must be greater than 0 and less than 300 seconds. |
| Client create ID | Uppercase ULID or hyphenated GUID. |
| Metadata | JSON-compatible ticket and player objects. |
The service requires a matching environment allowlist entry in addition to valid key syntax. The SDK validates parties more strictly than the raw request schema; direct clients should follow the same nonempty, unique-player convention.
Retention windows
| Record | Retention |
|---|---|
| Waiting ticket | 5 minutes after creation or its most recent successful confirm. |
| Matched ticket | 10 minutes after publication. |
| Match result | The same fixed 10-minute publication window. |
Confirm or cancel does not extend a matched result’s deadline. The SDK’s retained Match and Error properties are local in-memory outcomes, not persistent records.
Matching guarantees
A published group satisfies every member ticket’s constraints and contains tickets from one canonical environment. A match combines at least two tickets, even when one party already meets the player-count target.
Constraints do not promise that a compatible group will become available. Exact party sizes, missing metadata, sparse queues, and incompatible requirements can all keep a ticket waiting. A timeout rule only changes the boolean constraint tree that contains it.
Matching uses a greedy grouping process. It is not an optimization guarantee for the globally best combination of every waiting ticket.
Identity and retries
An existing ticket ID makes repeated creation return the original ticket unchanged. There is no permanent deduplication record after expiry or deletion. Never reuse a retired ID.
The SDK reconciles ambiguous creation with the known ID, and it does not create a replacement automatically. There is no exactly-once guarantee across record expiry, deletion, or an uncertain in-flight request.
Different sessions or clients can submit the same player. Your game must prevent overlapping searches. A correlation ref does not provide deduplication.
Delivery and cancellation
The API has three actions: create, confirm, and cancel. There is no acknowledgement action or per-match delivery tracking.
Cancellation cannot undo a published match. Handle matched as a possible cancellation response. Destroying an SDK client abandons local work; it does not revoke an in-flight request or remove every remote ticket.
Integration responsibilities
Your game owns player departure, party changes, session registries, server allocation, teleportation, and recovery after game-level handoff errors.
The current contract does not provide access-token authentication, SDK custom headers, or dashboard publication of matching rules. Define constraints in game code and use the service endpoint supplied for your deployment.
No universal maximum players per match, hosted rate limit, or production throughput tier is established by this contract. Set explicit playerCount limits appropriate to your game and validate capacity with the actual deployment.