Error codes

These are the Godot SDK error codes your game can meet when it calls PowerUp, what causes each one, and what to do about it. Every code here is stable: it keeps one meaning on every call, so you can branch on it safely. The codes come from two places: the SDK itself, for problems it catches before or instead of a request, and the server, for everything it refuses. What each method returns on success is in the SDK reference.

The result shape

Every call that talks to the server returns a Dictionary with ok. A failure carries these fields:

Three older calls differ: fetch_entitlements() returns an empty Array on failure, fetch_player() an empty Dictionary, and record_evidence() nothing at all. The request_failed(endpoint, reason) signal fires for every request that didn't succeed, whether the network failed or the server refused, which makes it a good place for logging. It doesn't fire for arguments the SDK rejects before sending.

# item is one entry of fetch_catalog()'s items, with price {coins} while it's for sale.
func _on_buy_pressed(item: Dictionary) -> void:
	var res := await buy_with_retry(item.key, int(item.price.coins))
	if res.ok:
		return
	var details: Dictionary = res.get("details", {})
	match res.code:
		"price_changed":
			_ask_again(item, details.priceCoins)  # show the new price, never charge it silently
		"insufficient_coins":
			_offer_coins(details.needed - details.balance)
		"wallet_in_debt":
			_toast("Coins are on hold until a refund is repaid")
		"already_owned":
			_mark_owned(item)
		_:
			_toast("That didn't work. Try again in a moment.")
			push_warning("%s (%s)" % [res.error, res.code])

Retrying safely

Calls that spend or grant (buying, claiming, redeeming a reward, starting a checkout) send an idempotency key. The server stores its answer under that key for 24 hours, in the same transaction as the effect, so a request that committed and then lost its answer is replayed, never run twice.

• Use one key per player action, and the same key for every retry of that action. Leave the idempotency_key argument empty and the SDK makes one and returns it in the result, on failures too.
• Retry transport_error and 5xx statuses with that key. A server error isn't stored, so the retry runs it fresh.
• idempotency_conflict means the key was already used. With details.inFlight true, the first attempt is still running: wait a moment and retry with the same key. With it false, the same key was sent with a different request, which is a bug: make a new key for each new action.
• Don't resend any other 4xx with the same key. A refusal is stored like any answer, so the same key brings back the same refusal. Fix the cause first, then make a new key for the new attempt. After rate_limited, wait retry_after seconds and try again with a new key.
• Never retry a code redeem automatically. Redeeming a transfer or recovery code, like register_player(), sends no key, because its answer carries a token that is never stored. Every wrong code also counts toward a limit.

func buy_with_retry(item_key: String, price: int) -> Dictionary:
	var key := PowerUp.new_idempotency_key()  # one key for this tap, every attempt
	var res: Dictionary = {}
	for attempt in 3:
		res = await PowerUp.buy_item(item_key, price, key)
		if res.ok or not _retryable(res):
			return res
		await get_tree().create_timer(1.0 + attempt * 2.0).timeout
	return res

func _retryable(res: Dictionary) -> bool:
	if res.code == "transport_error":
		return true
	if res.code == "idempotency_conflict":
		return bool((res.get("details", {}) as Dictionary).get("inFlight", false))
	return int(res.get("status", 0)) >= 500

Codes the SDK decides itself

These come back without a request, or because the request never got an answer. None of them has a server status, except where noted.

Codes from the server

Keys, players and requests

Age, consent and spending

These come from the rules on players and accounts. Each one is a decision the server made about this player, so don't try to work around it in the client.

Coins, items and rewards

Payments

The flows behind these are on payments.

A few answers that look like failures come back with ok: true and say so in the body: a receipt that was a duplicate, a test purchase, or a Family Sharing purchase; a restore with skipped entries; and an ad session that was rejected. Read the body, not just ok.

Match tickets, boosts and ads

Accounts

transfer_code_invalid, recovery_code_invalid, ownership_unproven and rate_limited also apply here. PowerUpDisclosure.transfer_refusal_text(code, details) puts every one of them in the player's words.

Clubs

For every club code, PowerUpDisclosure.club_refusal_text(code, details) gives the line to show.

Words for players

You rarely need to write refusal text yourself. These PowerUpDisclosure functions take a code (or the answer that carries it) and return the line a player reads:

The full list is in the SDK reference.