CloudWatch alarm for API Gateway 5XXError (REST API)
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.
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
| Setting | Value |
|---|---|
| Namespace | AWS/ApiGateway |
| Metric | 5XXError |
| Dimensions | ApiName, Stage |
| Statistic | Average |
| Period | 60 seconds |
| Datapoints to alarm | 3 |
| Evaluation periods | 3 |
| Comparison operator | GreaterThanThreshold |
| Threshold | 0.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:
- Graph
Averageof5XXErrorat one-minute resolution for 14 days. - Note the highest value outside known incidents.
- 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-2Use 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 see | Likely cause | Next step |
|---|---|---|
| Mostly 502 | Lambda threw, timed out, or returned a body that is not valid proxy output | Check the function's Errors and logs; see 502 Malformed Lambda proxy response |
| Mostly 504 | Integration ran past the integration timeout (29 seconds by default) | Compare IntegrationLatency; see 504 Endpoint request timed out |
| 500 with no backend logs | API 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 backend | Application or database failure | Follow 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.
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