Error codes

Errors return a JSON body { "error": { "code": "…", "message": "…" } } with the HTTP status below. Branch on code, not on the message text.

Authentication

code	HTTP	when
MISSING_HEADERS	401	a required signing header is absent
INVALID_SIGNATURE	401	unknown/revoked key or signature mismatch
TIMESTAMP_SKEW	401	timestamp outside ±300s

Launch & session

code	HTTP	when
GAME_DISABLED	403	game not in the operator’s enabled games
TENANT_SUSPENDED	403	operator is suspended
UNKNOWN_BOX	404	box not found
BOX_NOT_PLAYABLE	409	box inactive or has no current version
LAUNCH_TOKEN_INVALID	401	unknown / malformed launch token
LAUNCH_TOKEN_EXPIRED	401	past expiresAt
LAUNCH_TOKEN_CONSUMED	409	already exchanged for a session
SESSION_INVALID	401	unknown / revoked session token
SESSION_EXPIRED	401	past idle or max expiry

Purchase, cancel & wallet

code	HTTP	when
INSUFFICIENT_FUNDS	422	wallet refused — balance
PLAYER_BLOCKED	403	wallet refused — player state
WALLET_UNAVAILABLE	503	wallet timeout / 5xx / unconfigured
ROUND_NOT_FOUND	404	round not found / not owned
ROUND_NOT_HELD	409	opening a round that isn’t held
ROUND_NOT_REFUNDABLE	409	cancelling a round that isn’t held
REFUND_NOT_ALLOWED	403	operator/box policy forbids refunds
FX_RATE_MOVED	422	open in a non-base currency (player-API or S2S /purchase) — the display-currency exchange rate moved past the operator’s tolerance (or became unavailable) since the price was shown; retry to re-quote at the current price

Inventory, cashback & shipping

code	HTTP	when
INVENTORY_ITEM_NOT_FOUND	404	item not found or not owned
CASHBACK_NOT_AVAILABLE	422	item not unresolved, disabled, or no rule
INVENTORY_NOT_SHIPPABLE	422	batch contained a non-shippable item
SHIPPING_DISABLED	403	operator has shipping off
ORDER_NOT_FOUND	404	shipping order doesn’t exist for this player

Fairness & localization

code	HTTP	when
INVALID_CLIENT_SEED	422	malformed clientSeed on rotate
UNSUPPORTED_LOCALE	422	locale not configured for the operator
UNSUPPORTED_CURRENCY	422	currency not configured for the operator

Validation

A malformed request body returns 422 with field-level details under error.fields.