Skip to content

Errors, retries and idempotency

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 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.

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 carries Retry-After in 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.

A refused call throws RudderError (TypeScript) or RudderException (C#) with:

FieldMeaning
code / CodeWhat went wrong, a stable string to branch on.
message / MessageA sentence for logs, not for players.
status / StatusThe 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:

StatusCodesWhat to do
400invalid_request, invalid_argumentsA bug in the call: the arguments do not match the function.
401invalid_key, unauthorizedCheck the SDK key; the SDK handles an expired token.
403player_banned, player_deletedTell the player; the account is closed or paused.
404module_not_found, function_not_found, player_not_foundThe 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.
409idempotency_key_reusedA key was used for another call. Use a key per call.
422release_not_foundThe environment has no release yet. Publish one.
429rate_limitedBack off for Retry-After seconds.
500internal, module_timeoutA module failed or ran too long. Nothing changed.
503try_again, module_unsupportedSent 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.

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.