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

Upgrader

code	HTTP	when
UPGRADER_MODE_DISABLED	403	the operator has the requested Upgrader wager mode off
UPGRADER_WAGER_OUT_OF_RANGE	422	wager below the min or above the max
UPGRADER_CHANCE_INVALID	422	chance isn’t a configured preset, or exceeds the house-edge cap
UPGRADER_PRIZE_OUT_OF_RANGE	422	the target item isn’t an eligible prize, or its value is outside the band

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
PRICE_CHANGED	409	cashback on a collectible whose expectedRevisionId is no longer current — nothing settled; the body’s error.current carries the fresh figures to re-confirm with
INVENTORY_NOT_SHIPPABLE	422	batch contained a non-shippable item
SHIPMENT_BELOW_MINIMUM	422	the batch’s items add up to less than the operator’s shipping minimum; carries minimumMinor, valueMinor, currency
SHIPPING_DISABLED	403	operator has shipping off
ORDER_NOT_FOUND	404	shipping order doesn’t exist for this player
GOODS_ADDRESS_MISMATCH	409	a goods grant sent an address while shipping is off, or none while it is on; carries shippingEnabled
GOODS_NOT_SELLABLE	422	a goods grant named an item that is not an active physical item with a value; carries itemIds
GOODS_OUT_OF_STOCK	409	a goods grant named an item out of stock; carries itemIds
GOODS_IDEMPOTENCY_CONFLICT	409	a goods grant reused an idempotencyKey for other goods or another player
PAYOUT_ITEMS_NOT_WITHDRAWABLE	422	item payout quote or reserve named an item that is not the player’s or cannot be withdrawn; carries inventoryItemIds
PAYOUT_ITEMS_NOT_RESERVED	409	item payout confirm named an item not reserved under the payoutReference; carries inventoryItemIds
PAYOUT_ITEMS_PAID_OUT	409	item payout release named an item already paid out; carries inventoryItemIds

KYC

code	HTTP	when
KYC_DISABLED	403	KYC is not enabled for the operator
KYC_ALREADY_SUBMITTED	409	the player’s verification is already submitted and awaiting review
KYC_NO_OPEN_REQUEST	404	no open verification to update — a benign outcome for the email refresh
KYC_NOT_CONFIRMED	409	no confirmed verification to re-open — mint a session instead for a first-time (or post-rejection) verification

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.