Errors, retries and idempotency
A reward is never paid twice
Section titled “A reward is never paid twice”Every mutation carries an Idempotency-Key. Rudder keeps the answer of a mutation under its
key, and the same key sent again by the same player gets that answer back without running
anything:
- A mutation runs at most once per key. A purchase sent three times because the network dropped twice pays once and grants once.
- A repeated key gets the result of the run that succeeded. A refused call keeps nothing under its key: the same key sent later runs the function then, such as a purchase sent again after the player got enough gems.
- A key is remembered for at least 24 hours.
- A key the player already used for another function (or another module, or the game server)
is refused with 409
idempotency_key_reused, never mixed up with the first call.
The SDK makes a new random key for each mutation and keeps it across its own retries. That covers a lost answer while the game runs. To keep the promise across a restart of the game, give the key yourself, from something the game already keeps, such as the id of an order:
await rudder.stores.buy({ offer: 'starter' }, { idempotencyKey: `order-${orderId}` });await rudder.Stores.Buy(new BuyArguments { Offer = "starter" }, new RudderSdk.MutationOptions { IdempotencyKey = $"order-{orderId}" });A key is at most 128 characters. Queries change nothing and carry no key.
A call changes all or nothing
Section titled “A call changes all or nothing”A function that is refused changed nothing: no balance moved, no item was granted, no event was sent. A refusal of a module the function called is taken back with it. So the game never has to undo half of a purchase.
Retries
Section titled “Retries”The SDK sends a request again, with the same headers and so the same Idempotency-Key, when:
- it got no answer (the network failed), or
- it got 503 (
try_again): Rudder could not serve it right now, and changed nothing.
It waits for the Retry-After of the answer, or else 0.5 s doubling up to 8 s with a random
part, and sends at most attempts times in all (5 by default). After the last attempt it throws
the last failure: a RudderError / RudderException for a 503, the error of the network
otherwise.
It does not retry:
- 429
rate_limited: the project is over its request limit. Back off yourself; the answer carriesRetry-Afterin seconds. - Any other refusal: sending it again gets the same answer.
When the access token has expired (unauthorized), the SDK signs the device in again once and
sends the call again.
Refusals
Section titled “Refusals”A refused call throws RudderError (TypeScript) or RudderException (C#) with:
| Field | Meaning |
|---|---|
code / Code | What went wrong, a stable string to branch on. |
message / Message | A sentence for logs, not for players. |
status / Status | The HTTP status. |
A code is either one the module declares, with status 422 (Stores: limit_reached,
sold_out; any module: insufficient when a balance is too low), or one of Rudder:
| Status | Codes | What to do |
|---|---|---|
| 400 | invalid_request, invalid_arguments | A bug in the call: the arguments do not match the function. |
| 401 | invalid_key, unauthorized | Check the SDK key; the SDK handles an expired token. |
| 403 | player_banned, player_deleted | Tell the player; the account is closed or paused. |
| 404 | module_not_found, function_not_found, player_not_found | The release lacks the module or function: regenerate the client from the release the game reaches. The player was deleted while its token was still valid: treat the account as closed. |
| 409 | idempotency_key_reused | A key was used for another call. Use a key per call. |
| 422 | release_not_found | The environment has no release yet. Publish one. |
| 429 | rate_limited | Back off for Retry-After seconds. |
| 500 | internal, module_timeout | A module failed or ran too long. Nothing changed. |
| 503 | try_again, module_unsupported | Sent again by the SDK. |
An answer that is not one of Rudder (a proxy page, say) throws with the code
invalid_response. The full list is in Error codes.
Events after a call
Section titled “Events after a call”A mutation may start work that happens just after it, in another module or for another player (a quest that counts a purchase, a gift sent to a friend). That work is never lost and never undoes the call, but a query sent right after the call may not see it yet.