When it is safe to do so, the library automatically retries requests that fail due to a transient error. The library then uses exponential backoff to backoff before trying again. Which operations are considered safe to retry, which errors are treated as transient failures, the details of the exponential backoff algorithm, and for how long the library retries are all configurable via policies.
This document provides examples showing how to override the default policies.
The policies can be set when the *Connection object is created. The library provides default policies for any policy that is not set. The application can also override some (or all) policies when the *Client object is created. This can be useful if multiple *Client objects share the same *Connection object, but you want different retry behavior in some of the clients. Finally, the application can override some retry policies when calling a specific member function.
The library uses three different options to control the retry loop. The options have per-client names.
Configuring the transient errors and retry duration
The *RetryPolicyOption controls:
Which errors are to be treated as transient errors.
How long the library will keep retrying transient errors.
You can provide your own class for this option. The library also provides two built-in policies:
*LimitedErrorCountRetryPolicy: stops retrying after a specified number of transient errors.
*LimitedTimeRetryPolicy: stops retrying after a specified time.
Note that a library may have more than one version of these classes. Their name match the *Client and *Connection object they are intended to be used with. Some *Client objects treat different error codes as transient errors. In most cases, only kUnavailable is treated as a transient error.
Controlling the backoff algorithm
The *BackoffPolicyOption controls how long the client library will wait before retrying a request that failed with a transient error. You can provide your own class for this option.
The only built-in backoff policy is ExponentialBackoffPolicy. This class implements a truncated exponential backoff algorithm, with jitter. In summary, it doubles the current backoff time after each failure. The actual backoff time for an RPC is chosen at random, but never exceeds the current backoff. The current backoff is doubled after each failure, but never exceeds (or is "truncated") if it reaches a prescribed maximum.
Controlling which operations are retryable
The *IdempotencyPolicyOption controls which requests are retryable, as some requests are never safe to retry.
Only one built-in idempotency policy is provided by the library. The name matches the name of the client it is intended for. For example, FooBarClient will use FooBarIdempotencyPolicy. This policy is very conservative.
Example
For example, this will override the retry policies for vision_v1::ImageAnnotatorClient:
auto options =
google::cloud::Options{}
.set<google::cloud::vision_v1::
ImageAnnotatorConnectionIdempotencyPolicyOption>(
CustomIdempotencyPolicy().clone())
.set<google::cloud::vision_v1::ImageAnnotatorRetryPolicyOption>(
google::cloud::vision_v1::
ImageAnnotatorLimitedErrorCountRetryPolicy(3)
.clone())
.set<google::cloud::vision_v1::ImageAnnotatorBackoffPolicyOption>(
google::cloud::ExponentialBackoffPolicy(
/*initial_delay=*/std::chrono::milliseconds(200),
/*maximum_delay=*/std::chrono::seconds(45),
/*scaling=*/2.0)
.clone());
auto connection =
google::cloud::vision_v1::MakeImageAnnotatorConnection(options);
// c1 and c2 share the same retry policies
auto c1 = google::cloud::vision_v1::ImageAnnotatorClient(connection);
auto c2 = google::cloud::vision_v1::ImageAnnotatorClient(connection);
// You can override any of the policies in a new client. This new client
// will share the policies from c1 (or c2) *except* for the retry policy.
auto c3 = google::cloud::vision_v1::ImageAnnotatorClient(
connection,
google::cloud::Options{}
.set<google::cloud::vision_v1::ImageAnnotatorRetryPolicyOption>(
google::cloud::vision_v1::ImageAnnotatorLimitedTimeRetryPolicy(
std::chrono::minutes(5))
.clone()));
// You can also override the policies in a single call:
// c3.SomeRpc(..., google::cloud::Options{}
// .set<google::cloud::vision_v1::ImageAnnotatorRetryPolicyOption>(
// google::cloud::vision_v1::ImageAnnotatorLimitedErrorCountRetryPolicy(10).clone()));
This assumes you have created a custom idempotency policy. Such as:
class CustomIdempotencyPolicy : public google::cloud::vision_v1::
ImageAnnotatorConnectionIdempotencyPolicy {
public:
~CustomIdempotencyPolicy() override = default;
std::unique_ptr<
google::cloud::vision_v1::ImageAnnotatorConnectionIdempotencyPolicy>
clone() const override {
return std::make_unique<CustomIdempotencyPolicy>(*this);
}
// Override inherited functions to define as needed.
};
Follow these links to find examples for other *Client classes:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-14 UTC."],[[["\u003cp\u003eThe library automatically retries requests that fail due to transient errors, using exponential backoff with configurable policies that determine which errors are transient, how long to retry, and the backoff algorithm.\u003c/p\u003e\n"],["\u003cp\u003eRetry policies, including \u003ccode\u003e*RetryPolicyOption\u003c/code\u003e, \u003ccode\u003e*BackoffPolicyOption\u003c/code\u003e, and \u003ccode\u003e*IdempotencyPolicyOption\u003c/code\u003e, can be set when the \u003ccode\u003e*Connection\u003c/code\u003e object is created, or overridden at the \u003ccode\u003e*Client\u003c/code\u003e object level for varied behavior among clients, and even for individual function calls.\u003c/p\u003e\n"],["\u003cp\u003eBuilt-in retry policies include \u003ccode\u003e*LimitedErrorCountRetryPolicy\u003c/code\u003e and \u003ccode\u003e*LimitedTimeRetryPolicy\u003c/code\u003e for controlling the number of retries or duration, and \u003ccode\u003eExponentialBackoffPolicy\u003c/code\u003e for handling backoff with a random factor, while there is a conservative built-in idempotency policy.\u003c/p\u003e\n"],["\u003cp\u003eUsers can create custom classes for retry policies to define their own error handling, backoff, and retry behavior.\u003c/p\u003e\n"],["\u003cp\u003eExamples show how to override default policies, set up custom policies like \u003ccode\u003eCustomIdempotencyPolicy\u003c/code\u003e, and find code snippets for other \u003ccode\u003e*Client\u003c/code\u003e classes, such as \u003ccode\u003evision_v1::ImageAnnotatorClient\u003c/code\u003e and \u003ccode\u003evision_v1::ProductSearchClient\u003c/code\u003e.\u003c/p\u003e\n"]]],[],null,["Version 2.21.0keyboard_arrow_down\n\n- [2.42.0-rc (latest)](/cpp/docs/reference/vision/latest/vision-override-retry)\n- [2.41.0](/cpp/docs/reference/vision/2.41.0/vision-override-retry)\n- [2.40.0](/cpp/docs/reference/vision/2.40.0/vision-override-retry)\n- [2.39.0](/cpp/docs/reference/vision/2.39.0/vision-override-retry)\n- [2.38.0](/cpp/docs/reference/vision/2.38.0/vision-override-retry)\n- [2.37.0](/cpp/docs/reference/vision/2.37.0/vision-override-retry)\n- [2.36.0](/cpp/docs/reference/vision/2.36.0/vision-override-retry)\n- [2.35.0](/cpp/docs/reference/vision/2.35.0/vision-override-retry)\n- [2.34.0](/cpp/docs/reference/vision/2.34.0/vision-override-retry)\n- [2.33.0](/cpp/docs/reference/vision/2.33.0/vision-override-retry)\n- [2.32.0](/cpp/docs/reference/vision/2.32.0/vision-override-retry)\n- [2.31.0](/cpp/docs/reference/vision/2.31.0/vision-override-retry)\n- [2.30.0](/cpp/docs/reference/vision/2.30.0/vision-override-retry)\n- [2.29.0](/cpp/docs/reference/vision/2.29.0/vision-override-retry)\n- [2.28.0](/cpp/docs/reference/vision/2.28.0/vision-override-retry)\n- [2.27.0](/cpp/docs/reference/vision/2.27.0/vision-override-retry)\n- [2.26.0](/cpp/docs/reference/vision/2.26.0/vision-override-retry)\n- [2.25.1](/cpp/docs/reference/vision/2.25.1/vision-override-retry)\n- [2.24.0](/cpp/docs/reference/vision/2.24.0/vision-override-retry)\n- [2.23.0](/cpp/docs/reference/vision/2.23.0/vision-override-retry)\n- [2.22.1](/cpp/docs/reference/vision/2.22.1/vision-override-retry)\n- [2.21.0](/cpp/docs/reference/vision/2.21.0/vision-override-retry)\n- [2.20.0](/cpp/docs/reference/vision/2.20.0/vision-override-retry)\n- [2.19.0](/cpp/docs/reference/vision/2.19.0/vision-override-retry)\n- [2.18.0](/cpp/docs/reference/vision/2.18.0/vision-override-retry)\n- [2.17.0](/cpp/docs/reference/vision/2.17.0/vision-override-retry)\n- [2.16.0](/cpp/docs/reference/vision/2.16.0/vision-override-retry)\n- [2.15.1](/cpp/docs/reference/vision/2.15.1/vision-override-retry)\n- [2.14.0](/cpp/docs/reference/vision/2.14.0/vision-override-retry)\n- [2.13.0](/cpp/docs/reference/vision/2.13.0/vision-override-retry)\n- [2.12.0](/cpp/docs/reference/vision/2.12.0/vision-override-retry)\n- [2.11.0](/cpp/docs/reference/vision/2.11.0/vision-override-retry) \n\nOverride Retry, Backoff, and Idempotency Policies\n=================================================\n\nWhen it is safe to do so, the library automatically retries requests that fail due to a transient error. The library then uses [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) to backoff before trying again. Which operations are considered safe to retry, which errors are treated as transient failures, the details of the exponential backoff algorithm, and for how long the library retries are all configurable via policies.\n\nThis document provides examples showing how to override the default policies.\n\nThe policies can be set when the `*Connection` object is created. The library provides default policies for any policy that is not set. The application can also override some (or all) policies when the `*Client` object is created. This can be useful if multiple `*Client` objects share the same `*Connection` object, but you want different retry behavior in some of the clients. Finally, the application can override some retry policies when calling a specific member function.\n\nThe library uses three different options to control the retry loop. The options have per-client names.\n\nConfiguring the transient errors and retry duration\n---------------------------------------------------\n\nThe `*RetryPolicyOption` controls:\n\n- Which errors are to be treated as transient errors.\n- How long the library will keep retrying transient errors.\n\nYou can provide your own class for this option. The library also provides two built-in policies:\n\n- `*LimitedErrorCountRetryPolicy`: stops retrying after a specified number of transient errors.\n- `*LimitedTimeRetryPolicy`: stops retrying after a specified time.\n\nNote that a library may have more than one version of these classes. Their name match the `*Client` and `*Connection` object they are intended to be used with. Some `*Client` objects treat different error codes as transient errors. In most cases, only [kUnavailable](https://cloud.google.com/cpp/docs/reference/common/latest/namespacegoogle_1_1cloud_1a90e17f75452470f0f3ee1a06ffe58847.html) is treated as a transient error.\n\nControlling the backoff algorithm\n---------------------------------\n\nThe `*BackoffPolicyOption` controls how long the client library will wait before retrying a request that failed with a transient error. You can provide your own class for this option.\n\nThe only built-in backoff policy is [`ExponentialBackoffPolicy`](https://cloud.google.com/cpp/docs/reference/common/latest/namespacegoogle_1_1cloud.html). This class implements a truncated exponential backoff algorithm, with jitter. In summary, it doubles the current backoff time after each failure. The actual backoff time for an RPC is chosen at random, but never exceeds the current backoff. The current backoff is doubled after each failure, but never exceeds (or is \"truncated\") if it reaches a prescribed maximum.\n\nControlling which operations are retryable\n------------------------------------------\n\nThe `*IdempotencyPolicyOption` controls which requests are retryable, as some requests are never safe to retry.\n\nOnly one built-in idempotency policy is provided by the library. The name matches the name of the client it is intended for. For example, `FooBarClient` will use `FooBarIdempotencyPolicy`. This policy is very conservative.\n\nExample\n-------\n\nFor example, this will override the retry policies for `vision_v1::ImageAnnotatorClient`: \n\n auto options =\n google::cloud::Options{}\n .set\u003cgoogle::cloud::vision_v1::\n ImageAnnotatorConnectionIdempotencyPolicyOption\u003e(\n CustomIdempotencyPolicy().clone())\n .set\u003cgoogle::cloud::vision_v1::ImageAnnotatorRetryPolicyOption\u003e(\n google::cloud::vision_v1::\n ImageAnnotatorLimitedErrorCountRetryPolicy(3)\n .clone())\n .set\u003cgoogle::cloud::vision_v1::ImageAnnotatorBackoffPolicyOption\u003e(\n google::cloud::ExponentialBackoffPolicy(\n /*initial_delay=*/std::chrono::milliseconds(200),\n /*maximum_delay=*/std::chrono::seconds(45),\n /*scaling=*/2.0)\n .clone());\n auto connection =\n google::cloud::vision_v1::MakeImageAnnotatorConnection(options);\n\n // c1 and c2 share the same retry policies\n auto c1 = google::cloud::vision_v1::ImageAnnotatorClient(connection);\n auto c2 = google::cloud::vision_v1::ImageAnnotatorClient(connection);\n\n // You can override any of the policies in a new client. This new client\n // will share the policies from c1 (or c2) *except* for the retry policy.\n auto c3 = google::cloud::vision_v1::ImageAnnotatorClient(\n connection,\n google::cloud::Options{}\n .set\u003cgoogle::cloud::vision_v1::ImageAnnotatorRetryPolicyOption\u003e(\n google::cloud::vision_v1::ImageAnnotatorLimitedTimeRetryPolicy(\n std::chrono::minutes(5))\n .clone()));\n\n // You can also override the policies in a single call:\n // c3.SomeRpc(..., google::cloud::Options{}\n // .set\u003cgoogle::cloud::vision_v1::ImageAnnotatorRetryPolicyOption\u003e(\n // google::cloud::vision_v1::ImageAnnotatorLimitedErrorCountRetryPolicy(10).clone()));\n\nThis assumes you have created a custom idempotency policy. Such as: \n\n class CustomIdempotencyPolicy : public google::cloud::vision_v1::\n ImageAnnotatorConnectionIdempotencyPolicy {\n public:\n ~CustomIdempotencyPolicy() override = default;\n std::unique_ptr\u003c\n google::cloud::vision_v1::ImageAnnotatorConnectionIdempotencyPolicy\u003e\n clone() const override {\n return std::make_unique\u003cCustomIdempotencyPolicy\u003e(*this);\n }\n // Override inherited functions to define as needed.\n };\n\nFollow these links to find examples for other `*Client` classes:\n\n- [`vision_v1::ImageAnnotatorClient`](/cpp/docs/reference/vision/2.21.0/vision_v1_1_1ImageAnnotatorClient-retry-snippet)\n- [`vision_v1::ProductSearchClient`](/cpp/docs/reference/vision/2.21.0/vision_v1_1_1ProductSearchClient-retry-snippet)\n\nMore Information\n----------------\n\n###### See Also\n\n[`google::cloud::Options`](https://cloud.google.com/cpp/docs/reference/common/latest/classgoogle_1_1cloud_1_1Options.html)\n\n###### See Also\n\n[`google::cloud::BackoffPolicy`](https://cloud.google.com/cpp/docs/reference/common/latest/namespacegoogle_1_1cloud.html)\n\n###### See Also\n\n[`google::cloud::ExponentialBackoffPolicy`](https://cloud.google.com/cpp/docs/reference/common/latest/namespacegoogle_1_1cloud.html)"]]
