How do I troubleshoot "ThrottlingException" and "Rate exceeded" errors in Amazon SNS?

Short description

Amazon SNS API calls can't exceed the maximum allowed API request rate for each AWS account and Region. If API requests exceed this API throttling quota, further API calls are throttled, and Amazon SNS returns a ThrottlingException error.

Amazon SNS ThrottlingException error message examples:

• "An error occurred (ThrottlingException) when calling the Subscribe operation: Rate exceeded"
• "An error occurred (ThrottlingException) when calling the ListOriginationNumbers operation: Rate exceeded"
• "An error occurred (ThrottlingException) when calling the ListPhoneNumbersOptedOut operation: Rate exceeded"
• "An error occurred (ThrottlingException) when calling the publish operation: Rate exceeded"
• "An error occurred (ThrottlingException) when calling the GetSMSAttributes operation: Rate exceeded"

Note: Amazon SNS API calls are throttled to improve service performance. For more information about Amazon SNS API throttling quotas, see Amazon Simple Notification Service endpoints and quotas.

Resolution

Identify the throttled API

Identify the API action that's causing the error

When the rate limit exceeds the allotted limit for an API call, you receive an error response. Check the error message or the error stack to identify the API action that's being throttled.

Use CloudTrail logs to check the event for the API call

Amazon SNS is integrated with AWS CloudTrail. CloudTrail captures API calls for Amazon SNS as events. These events include calls from the Amazon SNS console and code calls to the Amazon SNS API operations. The supported events are recorded in a CloudTrail event, along with other AWS service events as part of the event history. For more information on CloudTrail events, see Amazon SNS information in CloudTrail.
Note: A Publish or PublishBatch API request isn't supported for logging as events in CloudTrail.

Examine the Regional quotas

Even if you use the PublishBatch API instead of Publish API to send the messages, Regional quotas can cause throttling. For example, if your Regional quota is 30,000 messages per second, you can still exceed the rate limit in the following ways:

• You used the Publish action at a rate of 30,000 API requests per second to publish 30,000 messages (one message per API request).
• You used the PublishBatch action at a rate of 3,000 API requests per second to publish 30,000 messages (10 messages per batch API request).
• You used the Publish action at a rate of 10,000 API requests per second to publish 10,000 messages (one message per API request). You also used the PublishBatch action at a rate of 2,000 API requests per second to publish 20,000 messages (10 messages per batch API request). And, in doing so, you created a total of 30,000 messages published per second.

The messages-per-second quota is based on the number of messages published to an Amazon SNS Region, and it combines Publish and PublishBatch API requests. For more information, see Publish API throttling and Other API throttling in Amazon Simple Notification Service endpoints and quotas.

Best practices for preventing ThrottlingException errors

Stagger the intervals of the API calls

When using AWS API endpoints, use exponential backoff and retries to decrease the number of API calls being made. Use the following high-level example pseudocode for exponential backoff and retries:

MakeSDKRequest() {
  attempts = 0
  loop {
    GetSendToken()
    response = SNSAPIRequest()
    RequestBookkeeping(response)
    if not Retryable(response)
      return response
    attempts += 1
    if attempts >= MAX_ATTEMPTS:
      return response
    if not HasRetryQuota(response)
      return response
    delay = ExponentialBackoff(attempts)
    sleep(delay)
  }
}

Request a service quota increase

If you continue to receive ThrottlingException errors after implementing exponential backoff and retries, request a service quota increase for the API that's creating the error. In the use case description, include the time frame when the throttle occurred and the reason that you're requesting a quota increase.

You can also refer to the Service quota dashboard for the SNS service current quota.
Note: Make sure that you request the service quota increase for your AWS Region.

Important: You can request service quota increases for soft-limit, Amazon SNS quotas only. You can't increase hard-limit, Amazon SNS quotas. For more information, see Service quotas.