What is a gRPC retry policy?

It is a per-method block in the service config JSON that tells the client library to automatically re-send a failed RPC. It defines the maximum number of attempts, an exponential backoff schedule, and the set of status codes that are considered retryable.

How does retryPolicy differ from hedgingPolicy?

retryPolicy sends one attempt, waits for it to fail, then backs off and retries sequentially. hedgingPolicy sends an extra attempt every hedgingDelay without waiting for the previous one to fail, then uses whichever responds first. A method may configure one or the other, never both.

Which status codes are retryable?

Only codes you list in retryableStatusCodes are retried, given as the gRPC status name (e.g. UNAVAILABLE) or its integer. Common safe choices are UNAVAILABLE and RESOURCE_EXHAUSTED; avoid retrying non-idempotent calls on codes like ABORTED unless the server is designed for it.

How is the backoff calculated?

The first retry waits a random delay in [0, initialBackoff). Each subsequent delay is the previous one multiplied by backoffMultiplier, capped at maxBackoff, with jitter applied. This spreads retries and avoids thundering-herd retries against a struggling server.

Does this tool need a network connection?

No. The field reference and search run entirely in your browser. Nothing is sent to a server.

gRPC Retry Policy Fields

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

gRPC automatic retry and hedging config

gRPC clients can retry failed RPCs automatically when the service config JSON declares a retryPolicy or hedgingPolicy under a method’s methodConfig entry. This reference lists every field in both policies with its JSON type, whether it is required, and what it controls, plus a live search.

How it works

A retryPolicy retries sequentially: attempt 1 fails, the client waits a backoff interval, then attempt 2 runs, and so on up to maxAttempts. The wait grows exponentially:

"retryPolicy": {
  "maxAttempts": 4,
  "initialBackoff": "0.1s",
  "maxBackoff": "1s",
  "backoffMultiplier": 2,
  "retryableStatusCodes": ["UNAVAILABLE", "RESOURCE_EXHAUSTED"]
}

A hedgingPolicy instead fires a new attempt every hedgingDelay without waiting, and the first successful response wins. Durations are strings ending in s (e.g. "0.5s"). Exactly one of the two policies may appear per method.

Tips and notes

maxAttempts counts the original call, so 4 means up to 3 retries.
Only list status codes that are safe to retry for that method’s idempotency.
Set a non-retryable fallback by omitting retryableStatusCodes entirely.
The total retry buffer is also bounded by the channel’s retryThrottling.