CloudConsole

CloudWatch alarm for API Gateway 5XXError (REST API)

Updated 16 November 2026 · How we write and check guides

Short answer

Alarm on 5XXError for each REST API stage with the Average statistic, which is the fraction of requests that ended in a 5xx. AWS recommends going into ALARM when that fraction exceeds 0.05 in 3 consecutive one-minute periods, three minutes rather than five because server errors hurt every caller.

Chart of the 5XXError alarm: Average per 1-minute period, ALARM when 3 of 3 datapoints are > 0.05
How the recommended alarm evaluates, with AWS's settings from this page. The metric values are illustrative.

What the metric counts

API Gateway emits a 1 or a 0 for 5XXError on every request to a REST API stage, so the Average over a minute is the server-error rate for that minute. The errors come from two places, and telling them apart is most of the diagnosis:

  • Your backend returned a 5xx and API Gateway passed it through (a Lambda proxy integration that returned statusCode: 500, an HTTP backend in trouble).
  • API Gateway generated the 5xx itself: 502 when a Lambda response is malformed or the function errored, 504 when the integration exceeded its timeout, 500 for internal or configuration faults such as a missing invoke permission.

Recommended alarm settings

SettingValue
NamespaceAWS/ApiGateway
Metric5XXError
DimensionsApiName, Stage
StatisticAverage
Period60 seconds
Datapoints to alarm3
Evaluation periods3
Comparison operatorGreaterThanThreshold
Threshold0.05: more than 5% of requests

Values from AWS's CloudWatch recommended alarms page. Note the shorter window than the 4XXError alarm: three breaching minutes out of three.

Tuning without losing the signal

5% is generous for most production APIs. A payments or login API may want 1%, while an internal API fronting a flaky legacy system may sit at 2% all day. To choose:

  1. Graph Average of 5XXError at one-minute resolution for 14 days.
  2. Note the highest value outside known incidents.
  3. Set the threshold roughly double that, but no higher than the error rate at which customers notice.

On a quiet stage, two failures out of twenty requests is 10%; if that is normal noise for you, pair the rate with a minimum request count using metric math rather than raising the threshold for everyone. Treat missing data as notBreaching, since no traffic means no errors.

Create it

aws cloudwatch put-metric-alarm \
  --alarm-name orders-api-prod-5xx-rate \
  --namespace AWS/ApiGateway \
  --metric-name 5XXError \
  --dimensions Name=ApiName,Value=orders-api Name=Stage,Value=prod \
  --statistic Average \
  --period 60 \
  --evaluation-periods 3 \
  --datapoints-to-alarm 3 \
  --threshold 0.05 \
  --comparison-operator GreaterThanThreshold \
  --treat-missing-data notBreaching \
  --alarm-actions arn:aws:sns:eu-west-2:123456789012:ops-alerts \
  --region eu-west-2

Use the REST API's name as ApiName. If you renamed the API, the metrics follow the new name and an alarm on the old one silently goes to INSUFFICIENT_DATA.

Runbook when it fires

What you seeLikely causeNext step
Mostly 502Lambda threw, timed out, or returned a body that is not valid proxy outputCheck the function's Errors and logs; see 502 Malformed Lambda proxy response
Mostly 504Integration ran past the integration timeout (29 seconds by default)Compare IntegrationLatency; see 504 Endpoint request timed out
500 with no backend logsAPI Gateway could not call the backend (permissions, VPC link, bad mapping template)Turn on execution logging for the stage and read the error for one request
5xx straight from backendApplication or database failureFollow the backend's own alarms

The re:Post guide on troubleshooting API Gateway 5xx errors covers the less common cases. A Logs Insights query to rank failures by path and status is on API Gateway 5xx errors in Logs Insights.

Questions

What is a good 5XXError threshold for API Gateway?

AWS suggests 0.05 (5% of requests) as a starting point. Most customer-facing APIs end up lower, between 1% and 2%, once they have looked at a couple of weeks of history.

Why does the 5XXError alarm only need 3 datapoints?

Server errors affect every caller, so AWS shortens the window to three minutes. Client errors (4XXError) use five because one bad client can skew them.

Does 5XXError include Lambda errors?

Yes, when the integration is Lambda. A function that throws or times out produces a 502 or 504 from API Gateway, which counts as 5XXError.

When this happens away from your desk

A 5xx alarm is the one that tends to fire at 3am. CloudConsole, a phone app for AWS, is built so you can read the alarm, the error trend and the backend logs from your phone before deciding whether to get up.

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