Throttling Amazon KMS requests - Amazon Key Management Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Throttling Amazon KMS requests

To ensure that Amazon KMS can provide fast and reliable responses to API requests from all customer, it throttles API requests that exceed certain boundaries.

Throttling occurs when Amazon KMS rejects a request that might otherwise be valid, and returns a ThrottlingException error like the following one.

You have exceeded the rate at which you may call KMS. Reduce the frequency of your calls. (Service: AWSKMS; Status Code: 400; Error Code: ThrottlingException; Request ID: <ID>

Amazon KMS throttles requests for the following conditions.

  • The rate of requests per second exceeds the Amazon KMS request quota for an account and Region.

    For example, if users in your account submit 1000 DescribeKey requests in a second, Amazon KMS throttles all subsequent DescribeKey requests in that second.

    To respond to throttling, use a backoff and retry strategy. This strategy is implemented automatically for HTTP 400 errors in some Amazon SDKs.

  • A burst or sustained high rate of requests to change the state of the same KMS key. This condition is often known as a "hot key."

    For example, if an application in your account sends a persistent volley of EnableKey and DisableKey requests for the same KMS key, Amazon KMS throttles the requests. This throttling occurs even if the requests don't exceed the request-per-second request limit for the EnableKey and DisableKey operations.

    To respond to throttling, adjust your application logic so it makes only required requests or it consolidates the requests of multiple functions.

  • Requests for operations on KMS keys in custom key stores might be throttled at a lower-than-expected rate when the Amazon CloudHSM cluster associated with the custom key store is processing numerous commands, including those unrelated to the custom key store.

    (Amazon KMS no longer throttles requests for operations on KMS keys in a custom key store when there are no available PKCS #11 sessions for the Amazon CloudHSM cluster. Instead, it throws a KMSInternalException and recommends that you retry your request.)

To view trends in your request rates, use the Service Quotas console. You can also create an Amazon CloudWatch alarm that alerts you when your request rate reaches a certain percentage of a quota value. For details, see Manage your Amazon KMS API request rates using Service Quotas and Amazon CloudWatch in the Amazon Security Blog.

All Amazon KMS quotas are adjustable, except for the key policy document size resource quota, the custom key store resource quota, and the Amazon CloudHSM key store request quota. To request a quota increase, see Requesting a quota increase in the Service Quotas User Guide. To request a quota decrease, to change a quota that is not listed in Service Quotas, or to change a quota in an Amazon Web Services Region where Service Quotas for Amazon KMS is not available, please visit Amazon Web Services Support Center and create a case.

Note

Amazon KMS custom key store request quotas do not appear in the Service Quotas console. You cannot view or manage these quotas by using Service Quotas API operations. To request a change to your external key store request quota, visit the Amazon Web Services Support Center and create a case.