CloudConsole

CloudWatch alarm for Amazon Cognito TokenRefreshThrottles

Updated 16 November 2026 · How we write and check guides

Short answer

TokenRefreshThrottles counts requests to exchange a refresh token for new tokens that a Cognito user pool rejected for exceeding its rate quota. AWS suggests an alarm on the Sum per UserPool and UserPoolClient above a threshold you set from history, for 5 of 5 one-minute periods, because short, retried throttles are expected.

Chart of the TokenRefreshThrottles alarm: Sum per 1-minute period, ALARM when 5 of 5 datapoints are > 40
How the recommended alarm evaluates, with AWS's settings from this page and the page's example threshold. The metric values are illustrative.

What drives token refresh volume

Every signed-in client periodically trades its refresh token for a fresh ID and access token. Volume is set by two things you control: how many sessions are active and how long access tokens last. Halve the access token validity and you roughly double the refresh rate for the same users.

Throttling usually starts after one of these:

  • Access token validity shortened in the app client settings, for security reasons, without checking the rate impact (the minimum is five minutes).
  • A client bug that refreshes on every API call or on every app resume, rather than when the token is close to expiry.
  • Synchronised refreshes: a fleet of devices or services that all signed in at the same moment and refresh at the same moment.
  • Genuine growth in concurrent sessions.

Recommended alarm settings

SettingValue
NamespaceAWS/Cognito
MetricTokenRefreshThrottles
DimensionsUserPool, UserPoolClient
StatisticSum
Period60 seconds
Datapoints to alarm5
Evaluation periods5
Comparison operatorGreaterThanThreshold
ThresholdDepends on your situation: above your normal, acceptable throttling level

From AWS's recommended alarms page. Unlike sign-up and sign-in, AWS does not suggest zero here; a few throttled refreshes that are retried a moment later are invisible to users.

Setting the threshold

  1. Graph TokenRefreshThrottles and TokenRefreshSuccesses (Sum, one minute) for four weeks.
  2. Find the typical peak of throttles on normal days, for example 15 a minute at the morning peak.
  3. Set the threshold comfortably above it, say 40, so the alarm only fires when throttling clearly exceeds the normal pattern.
  4. Revisit after changing token lifetimes or releasing a new client version.

Leave missing data as notBreaching.

Create it

# 40 is an example: set it above your normal peak of throttled refreshes
aws cloudwatch put-metric-alarm \
  --alarm-name userpool-mobile-refresh-throttles \
  --namespace AWS/Cognito \
  --metric-name TokenRefreshThrottles \
  --dimensions Name=UserPool,Value=eu-west-2_AbCdEf123 Name=UserPoolClient,Value=1h2j3k4l5m6n7o8p9q0r1s2t3u \
  --statistic Sum \
  --period 60 \
  --evaluation-periods 5 \
  --datapoints-to-alarm 5 \
  --threshold 40 \
  --comparison-operator GreaterThanThreshold \
  --treat-missing-data notBreaching \
  --alarm-actions arn:aws:sns:eu-west-2:123456789012:ops-alerts \
  --region eu-west-2

When it fires

  1. Check for a client release. A sudden step change in refresh volume that lines up with an app version rollout points to a refresh-on-every-call bug.
  2. Check app client settings for a recent change to access token validity:
    aws cognito-idp describe-user-pool-client --user-pool-id eu-west-2_AbCdEf123 \
      --client-id 1h2j3k4l5m6n7o8p9q0r1s2t3u \
      --query "UserPoolClient.[AccessTokenValidity,IdTokenValidity,TokenValidityUnits]"
  3. Make clients refresh lazily, a short time before expiry and with jitter, and back off on TooManyRequestsException.
  4. If real session growth is the cause, request a quota increase for the relevant category; see Quotas in Amazon Cognito.

Questions

Why are my Cognito token refreshes throttled?

Usually because clients refresh far more often than needed, access tokens were made very short-lived, or many sessions refresh at the same moment.

Does shortening access token validity increase Cognito traffic?

Yes. Every active session refreshes once per token lifetime, so a shorter lifetime means proportionally more refresh requests.

Should TokenRefreshThrottles alarm at zero?

Usually not. Occasional throttled refreshes are retried without users noticing, so set the threshold above your normal level.

When this happens away from your desk

Refresh throttling usually follows a client release and grows as users update. CloudConsole, a phone app for AWS, is built to show this alarm with its trend so you can see whether it is getting better or worse.

Did it start after a deploy? What changed? on the app’s alarm screen lists the deploys and configuration changes from the hour before the alarm fired.

About the app → · Download on the App Store

Sources