Preventing duplicate database transactions

In some circumstances, when a caller application is making a request that involves a commit to the database, the application may want to ensure that the request is processed only once. The caller application can do this using the GW-DBTransaction-ID header.

The GW-DBTransaction-ID header identifies a transaction ID (a string of up to 128 characters). When submitted with a Cloud API call, Cloud API attempts to insert the value into the database's TransactionID table.

  • If the value does not already exist in the table, the insert is successful. Cloud API assumes the transaction has not already been committed, and the call is processed as normal.
  • If the value does exist in the table, the insert fails. Cloud API assumes the transaction has already been committed, and the call is rejected. Cloud API returns a 400 status code with an gw.api.webservice.exception.AlreadyExecutedException error.

For the call to succeed, the transaction ID specified in the header must be globally unique across all clients, APIs, and web services.

The GW-DBTransaction-ID header has the following limitations:

  • It only works with Cloud API calls that commit data to the database.
  • It only works when Cloud API commits a single time only. (Cloud API calls that commit multiple times are rare.)
  • It only works if the commit is either the only side effect of the call, or if the commit happens before any other side effects, such as the sending of notifications to external systems.

Duplicate requests do not return identical responses. The first request will succeed, but subsequent requests will fail. It is the responsibility of the caller application to decide how or if to handle this situation.