Understanding retry policy with the driver in Amazon QLDB

Important

End of support notice: Existing customers will be able to use Amazon QLDB until end of support on 07/31/2025. For more details, see Migrate an Amazon QLDB Ledger to Amazon Aurora PostgreSQL.

The Amazon QLDB driver uses a retry policy to handle transient exceptions by transparently retrying a failed transaction. These exceptions, such as CapacityExceededException and RateExceededException, typically correct themselves after a period of time. If the transaction that failed with the exception is retried after a suitable delay, it's likely to succeed. This helps to improve the stability of the application that uses QLDB.

Types of retryable errors

The driver automatically retries a transaction if and only if any of the following exceptions occur during an operation within that transaction:

• CapacityExceededException – Returned when the request exceeds the processing capacity of the ledger.

• InvalidSessionException – Returned when a session is no longer valid or if the session doesn't exist.

• LimitExceededException – Returned if a resource limit such as number of active sessions is exceeded.

• OccConflictException – Returned when a transaction can't be written to the journal due to a failure in the verification phase of optimistic concurrency control (OCC).

• RateExceededException – Returned when the rate of requests exceeds the allowed throughput.

Default retry policy

The retry policy consists of a retry condition and a backoff strategy. The retry condition defines when a transaction should be retried, while the backoff strategy defines how long to wait before retrying the transaction.

When creating an instance of the driver, the default retry policy specifies to retry up to four times, and to use an exponential backoff strategy. The exponential backoff strategy uses a minimum delay of 10 milliseconds and a maximum delay of 5000 milliseconds, with equal jitter. If the transaction can't be committed successfully within the retry policy, we recommend trying the transaction at another time.

The concept of exponential backoff is to use progressively longer wait times between retries for consecutive error responses. For more information, see the AWS blog post Exponential Backoff and Jitter.