이 페이지에서는 Identity and Access Management(IAM) API에 대한 실패한 요청을 재시도하기 위한 권장사항을 설명합니다.
안전하게 재시도할 수 있는 요청의 경우 지터가 도입된 잘린 지수 백오프를 사용하는 것이 좋습니다.
잘린 지수 백오프 개요
IAM API에 대한 각 요청은 성공하거나 실패할 수 있습니다. 대기 없이 애플리케이션 재시도가 실패하면 짧은 기간 내에 많은 수의 재시도가 IAM에 전송될 수 있습니다. 따라서 Google Cloud 프로젝트에서 모든 IAM 리소스에 적용되는 할당량 및 제한을 초과할 수 있습니다.
이 문제를 트리거하지 않으려면 네트워크 애플리케이션에 대한 표준 오류 처리 전략인 잡음이 도입된 잘린 지수 백오프를 사용하는 것이 좋습니다. 이 방법에서 클라이언트는 재시도 사이의 지연 시간을 기하급수적으로 늘리면서 실패한 요청을 주기적으로 재시도합니다. 또한 재시도 사이에 잡음이라고 하는 임의의 짧은 지연 시간이 추가됩니다. 이러한 임의의 지연은 Thundering Herd 문제라고도 하는 여러 클라이언트의 동기화된 재시도 웨이브를 방지하는 데 도움이 됩니다.
지수 백오프 알고리즘
다음 알고리즘은 지터가 포함된 잘린 지수 백오프를 구현합니다.
IAM에 요청을 전송합니다.
요청이 실패하면 1초 + random-fraction를 대기한 후 요청을 재시도합니다.
요청이 실패하면 2초 + random-fraction를 대기한 후 요청을 재시도합니다.
요청이 실패하면 4초 + random-fraction를 대기한 후 요청을 재시도합니다.
이 패턴을 계속 시도합니다. 재시도할 때마다 2n + random-fraction초 동안 대기합니다(최대 maximum-backoff시간).
deadline초가 지나면 요청 재시도를 중지합니다.
알고리즘을 구현할 때 다음 값을 사용합니다.
재시도를 하기 전 대기 시간은 min((2n + random-fraction), maximum-backoff)이며, n은 0에서 시작하고 재시도할 때마다 1씩 증가합니다.
random-fraction을 1보다 작거나 같은 임의의 소수 값으로 바꿉니다. 재시도할 때마다 다른 값을 사용하세요. 이 임의의 값을 추가하면 클라이언트가 동기화되고 동시에 다수의 재시도를 전송할 수 없습니다.
maximum-backoff를 재시도 사이의 최대 대기 시간(초)으로 바꿉니다. 일반적인 값은 32초 또는 64초(25 또는 26)입니다. 사용 사례에 가장 적합한 값을 선택하세요.
deadline을 재시도 전송을 유지할 최대 시간(초)으로 바꿉니다. 사용 사례에 맞는 값을 선택하세요. 예를 들어 시간에 크게 민감하지 않은 지속적 통합/지속적 배포(CI/CD) 파이프라인의 경우 deadline을 300초(5분)로 설정할 수 있습니다.
재시도할 오류 유형
오류 코드 500, 502, 503, 504를 반환하는 IAM API에 대한 모든 요청에 이 재시도 전략을 사용합니다.
선택적으로 오류 코드 404를 반환하는 IAM API에 대한 요청에 이 재시도 전략을 사용할 수 있습니다.
IAM 읽기는 eventual consistency를 가집니다. 결과적으로 리소스를 만든 직후에 리소스가 표시되지 않을 수 있으며 이로 인해 404 오류가 발생할 수 있습니다.
또한 오류 코드 409 및 상태 ABORTED를 반환하는 IAM API에 대한 모든 요청에 이 재시도 전략의 수정된 버전을 사용합니다. 이 유형의 오류는 동시성 문제를 나타냅니다. 예를 들어 다른 클라이언트가 이미 덮어쓴 허용 정책을 업데이트하려고 시도할 수 있습니다. 이 유형의 오류에서는 지터가 도입된 잘린 지수 백오프를 사용해서 항상 요청의 전체 read-modify-write 시리즈를 재시도해야 합니다. 쓰기 작업만 재시도하면 요청이 계속 실패합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\u003cp\u003eThis document outlines best practices for retrying failed requests to the Identity and Access Management (IAM) API, recommending the use of truncated exponential backoff with jitter for safe-to-retry requests.\u003c/p\u003e\n"],["\u003cp\u003eUsing truncated exponential backoff with jitter helps prevent overwhelming the IAM API with a large number of retries, which can lead to exceeding project quotas and limits.\u003c/p\u003e\n"],["\u003cp\u003eThe retry algorithm involves exponentially increasing wait times between retries, with the addition of a random delay (jitter) to avoid synchronized retries from multiple clients, and a cap on the wait time, followed by a final deadline.\u003c/p\u003e\n"],["\u003cp\u003eThe recommended retry strategy should be used for IAM API requests that return \u003ccode\u003e500\u003c/code\u003e, \u003ccode\u003e502\u003c/code\u003e, \u003ccode\u003e503\u003c/code\u003e, or \u003ccode\u003e504\u003c/code\u003e error codes, and optionally \u003ccode\u003e404\u003c/code\u003e errors due to eventual consistency, and a modified version should be used for \u003ccode\u003e409\u003c/code\u003e \u003ccode\u003eABORTED\u003c/code\u003e errors.\u003c/p\u003e\n"],["\u003cp\u003eFor \u003ccode\u003e409\u003c/code\u003e errors, which typically signify concurrency issues, you should retry the entire read-modify-write series of requests, as retrying only the write operation will not resolve the issue.\u003c/p\u003e\n"]]],[],null,["# Retry failed requests\n\nThis page describes best practices for retrying failed requests to the\nIdentity and Access Management (IAM) API.\n\nFor requests that are safe to retry, we recommend using truncated exponential backoff with introduced jitter.\n\nOverview of truncated exponential backoff\n-----------------------------------------\n\n\nEach request to the IAM API can succeed or fail. If your application retries\nfailed requests without waiting, it might send a large number of retries to IAM\nin a short period of time. As a result, you might exceed [quotas and limits](/iam/quotas) that apply to every\nIAM resource in your Google Cloud project.\n\n\nTo avoid triggering this issue, we strongly recommend that you use\n[truncated exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) with\nintroduced [jitter](https://en.wikipedia.org/wiki/Jitter), which is a standard\nerror-handling strategy for network applications. In this approach, a client periodically retries\na failed request with exponentially increasing delays between retries. A small, random delay,\nknown as jitter, is also added between retries. This random delay helps prevent a synchronized\nwave of retries from multiple clients, also known as the\n[thundering herd problem](https://en.wikipedia.org/wiki/Thundering_herd_problem).\n\nExponential backoff algorithm\n-----------------------------\n\n\nThe following algorithm implements truncated exponential backoff with jitter:\n\n1. Send a request to IAM.\n2. If the request fails, wait 1 + `random-fraction` seconds, then retry the request.\n3. If the request fails, wait 2 + `random-fraction` seconds, then retry the request.\n4. If the request fails, wait 4 + `random-fraction` seconds, then retry the request.\n5. Continue this pattern, waiting 2^n^ + `random-fraction` seconds after each retry, up to a `maximum-backoff` time.\n6. After `deadline` seconds, stop retrying the request.\n\n\nUse the following values as you implement the algorithm:\n\n- Before each retry, the wait time is `min((2`^n^` + random-fraction), maximum-backoff)`, with `n` starting at 0 and incremented by 1 for each retry.\n- Replace `random-fraction` with a random fractional value less than or equal to 1. Use a different value for each retry. Adding this random value prevents clients from becoming synchronized and sending large numbers of retries at the same time.\n- Replace `maximum-backoff` with the maximum amount of time, in seconds, to wait between retries. Typical values are 32 or 64 (2^5^ or 2^6^) seconds. Choose the value that works best for your use case.\n- Replace `deadline` with the maximum number of seconds to keep sending retries. Choose a value that reflects your use case. For example, in a continuous integration/continuous deployment (CI/CD) pipeline that is not highly time-sensitive, you might set `deadline` to 300 seconds (5 minutes).\n\nTypes of errors to retry\n------------------------\n\nUse this retry strategy for all requests to the IAM API that\nreturn the error codes `500`, `502`, `503`, or `504`.\n\nOptionally, you can use this retry strategy for requests to the\nIAM API that return the error code `404`.\n[IAM reads are eventually consistent](/iam/docs/overview#consistency); as a\nresult, resources might not be visible immediately after you create them, which\ncan lead to `404` errors.\n\nIn addition, use a modified version of this retry strategy for all requests to\nthe IAM API that return the error code `409` and the status\n`ABORTED`. This type of error indicates a concurrency issue; for example, you\nmight be trying to update an [allow policy](/iam/docs/allow-policies) that another client has\nalready overwritten. For this type of error, you should always retry the entire\n[read-modify-write](/iam/docs/allow-policies#etag) series of requests, using\ntruncated exponential backoff with introduced jitter. If you retry only the write operation, the request will\ncontinue to fail.\n\nWhat's next\n-----------\n\n- Learn [how concurrency issues are managed](/iam/docs/allow-policies#etag) in allow policies.\n- Understand how to [implement the read-modify-write pattern](/iam/docs/granting-changing-revoking-access#programmatic) for updating allow policies."]]
