# CloudWatch alarm for API Gateway 5XXError (REST API)

CloudWatch alarms · Updated 16 November 2026

**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.

## 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](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html) 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 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](https://cloudconsole.dev/errors/api-gateway-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](https://cloudconsole.dev/errors/api-gateway-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](https://repost.aws/knowledge-center/api-gateway-5xx-error) 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](https://cloudconsole.dev/logs-insights/api-gateway-5xx-errors).

## 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.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [Recommended alarms for AWS services (Amazon CloudWatch User Guide)](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html)
- [API Gateway metrics and dimensions (REST APIs)](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-metrics-and-dimensions.html)

## Related

- [CloudWatch alarm for API Gateway 4XXError (REST API)](https://cloudconsole.dev/alarms/api-gateway-4xxerror)
- [CloudWatch alarm for API Gateway Latency (REST API stage)](https://cloudconsole.dev/alarms/api-gateway-latency)
- [502 Bad Gateway: Malformed Lambda proxy response](https://cloudconsole.dev/errors/api-gateway-502-malformed-lambda-proxy-response)
- [504: Endpoint request timed out](https://cloudconsole.dev/errors/api-gateway-504-endpoint-request-timed-out)
- [API Gateway 5xx errors with Logs Insights](https://cloudconsole.dev/logs-insights/api-gateway-5xx-errors)
- [CloudWatch alarm: Lambda Errors](https://cloudconsole.dev/alarms/lambda-errors)

---

Source: https://cloudconsole.dev/alarms/api-gateway-5xxerror

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
