Skip to main content

Idempotency

1. Idempotency​

1.1 What Is Idempotency?​

An API call or operation is idempotent if it has the same result no matter how many times it's applied. That is, an idempotent operation provides protection against accidental duplicate calls causing unintended consequences. Idempotency ensures the safety of retrying API requests in certain situations, particularly when the initial request does not receive a response due to a network error. Given that intermittent failures are anticipated, clients need a way of reconciling failed requests with the server, and idempotency provides a mechanism for that.

Note: The currently supported PGOS HTTP APIs for idempotent operations are as follows:

  • BatchIncrPlayerKVData
  • IncrPlayerKVData
  • IncrPlayerKVData
  • GrantItemsToPlayer
  • GrantCurrencyToPlayer
  • BatchGrantVirtualCurrenciesToPlayer
  • SubtractPlayerVirtualCurrencies
  • SubtractPlayerCurrency
  • SubtractPlayerCurrency

1.2 Idempotency token expiration​

Idempotency token in all HTTP API has a expiration duration of 90 days, during which the idempotency is ensured for replayed requests using the same idempotency_token.Clients can safely retry requests that include an idempotency_token as long as the second request occurs within 90 days from the first time idempotency_token was used (Idempotency tokens expire out of the system after 90 days).

Usage notes​

  • idempotency_token must be unique for each request of an API call type. Check out the details of economy idempotent API.
  • Use an algorithm that generates a token with enough randomness, like UUID v4. Idempotency keys are up to 128 bytes long.
  • To identify a previously executed response that’s being replayed from the server, look for the rsp field replayed: true.