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

CloudWatch alarms · Updated 16 November 2026

**Short answer:** Alarm on the REST API metric 4XXError using the Average statistic, which API Gateway reports as the fraction of requests that returned a 4xx. AWS recommends alerting when that fraction is above 0.05 (5%) in 5 out of 5 one-minute periods for an ApiName and Stage pair.

## What 4XXError measures

For every request a REST API stage handles, API Gateway records `4XXError` as 1 if the response status was in the 400 range and 0 otherwise. That makes the statistic you pick matter: `Sum` gives you the number of client errors, while `Average` gives you the share of all requests that failed on the client side. The recommended alarm uses the share, so a traffic spike on its own does not trip it.

"Client-side" is API Gateway's view, not necessarily the truth. A 403 from a broken authorizer, a 429 from your own stage throttling or usage plan, and a 404 because a deploy removed a resource all land here, even though the fix is on your side.

## Recommended alarm settings

| Setting | Value |
|---|---|
| Namespace | `AWS/ApiGateway` |
| Metric | `4XXError` |
| Dimensions | `ApiName`, `Stage` |
| Statistic | `Average` |
| Period | 60 seconds |
| Datapoints to alarm | 5 |
| Evaluation periods | 5 |
| Comparison operator | `GreaterThanThreshold` |
| Threshold | 0.05: 5% of requests |

Source: the CloudWatch [recommended alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html) list for API Gateway. `ApiName` is the REST API's name, not its ID, and `Stage` is the stage name such as `prod`.

## Why these settings, and how to tune them

- **Five consecutive minutes above 5%** filters out a single misbehaving client retrying a bad token for a minute, but still pages you within about five minutes of a real regression.
- **Know your baseline before you trust 5%.** Some APIs legitimately return lots of 404s (lookups by ID) or 401s (expired sessions). Plot `Average` of `4XXError` over the last two weeks; set the threshold comfortably above the normal daily peak rather than on the median.
- **Low-traffic stages are noisy.** Ten requests a minute with one 404 is already 10%. Either raise the threshold, alarm on `Sum` instead, or add a metric-math condition that also requires a minimum request `Count`.
- **Missing data:** a stage with no requests in a minute publishes nothing. Treat missing data as `notBreaching` so quiet nights don't leave the alarm in `INSUFFICIENT_DATA`.
- **Per-method alarms** need detailed CloudWatch metrics turned on for the stage; they add the `Resource` and `Method` dimensions and cost extra custom-metric charges.

## Create it with the AWS CLI

```
aws cloudwatch put-metric-alarm \
  --alarm-name orders-api-prod-4xx-rate \
  --namespace AWS/ApiGateway \
  --metric-name 4XXError \
  --dimensions Name=ApiName,Value=orders-api Name=Stage,Value=prod \
  --statistic Average \
  --period 60 \
  --evaluation-periods 5 \
  --datapoints-to-alarm 5 \
  --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
```

Swap the SNS topic ARN for your own. The same values work in CloudFormation's `AWS::CloudWatch::Alarm` resource.

## When the alarm fires

1. **Split by status code.** Turn on access logging with `$context.status` in the format if it is not already, then count by status in Logs Insights. A wall of 403s is an auth problem, 429s are throttling, 404s are routing.
2. **Check what changed.** A deployment that renamed a resource path or tightened a request validator is the classic cause; compare the stage's deployment time with the start of the spike.
3. **For 429s,** compare stage and method throttle settings and any usage-plan limits with the request rate; the re:Post article on [API Gateway 429 errors](https://repost.aws/knowledge-center/api-gateway-429-limit) walks through it.
4. **For 403s,** look at the authorizer: an expired signing key, an IAM policy change or a Lambda authorizer that is itself failing. See [403 Forbidden from API Gateway](https://cloudconsole.dev/errors/api-gateway-403-forbidden) and [Missing Authentication Token](https://cloudconsole.dev/errors/api-gateway-missing-authentication-token).
5. **Find the caller.** Group the errors by source IP or API key; one broken client release often accounts for nearly all of them.

## Questions

### Is 4XXError a count or a rate?

Both, depending on the statistic. Sum gives the number of 4xx responses in the period; Average gives the fraction of requests that were 4xx, which is what the 0.05 threshold expects.

### Does 4XXError include 429 throttling?

Yes. Requests rejected by stage, method or usage-plan throttling return 429 and count as 4XXError, so a throttling problem can trigger this alarm.

### Should I alarm on 4XXError at all?

Yes, but loosely. Sustained client errors usually mean a broken deploy, auth change or client release; a single bad caller should not wake anyone, which is why the alarm needs five breaching minutes.

## When this happens away from your desk

A 4xx spike usually shows up right after someone else's release, often outside your working hours. CloudConsole, a phone app for AWS, is built to put the alarm, the API's recent deployments and the matching log lines on one phone screen.

[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 5XXError (REST API)](https://cloudconsole.dev/alarms/api-gateway-5xxerror)
- [403 Forbidden: User is not authorized to access this resource](https://cloudconsole.dev/errors/api-gateway-403-forbidden)
- [429 Too Many Requests from API Gateway](https://cloudconsole.dev/errors/api-gateway-429-too-many-requests)
- [{"message":"Missing Authentication Token"}](https://cloudconsole.dev/errors/api-gateway-missing-authentication-token)
- [aws cloudwatch put-metric-alarm](https://cloudconsole.dev/cli/cloudwatch-put-metric-alarm)
- [API Gateway 5xx errors with Logs Insights](https://cloudconsole.dev/logs-insights/api-gateway-5xx-errors)

---

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

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