# CloudWatch alarm for API Gateway ClientError (WebSocket API)

CloudWatch alarms · Updated 16 November 2026

**Short answer:** ClientError counts WebSocket API requests that API Gateway rejected with a 4xx before or instead of calling the integration. AWS recommends an alarm on its Average for an ApiId and Stage, firing when it is greater than 0.05 for 5 consecutive one-minute periods.

## What ClientError covers on a WebSocket API

WebSocket APIs do not have a `4xx` metric. Instead, client-side failures are reported as `ClientError`, separate from `IntegrationError` (the backend returned an error) and `ExecutionError` (calling the backend failed). Typical sources:

- **Rejected `$connect`** requests: a Lambda or IAM authorizer denied the connection, or the request was missing a required header or query string.
- **Messages to a route that does not exist** when there is no `$default` route to catch them, or a route selection expression that does not match the payload.
- **Throttled messages** once the stage, route or account limit is exceeded.
- **Oversized frames or messages** beyond the WebSocket API limits.

## Recommended settings

| Setting | Value |
|---|---|
| Namespace | `AWS/ApiGateway` |
| Metric | `ClientError` |
| Dimensions | `ApiId`, `Stage` |
| Statistic | `Average` |
| Period | 60 seconds |
| Datapoints to alarm | 5 |
| Evaluation periods | 5 |
| Comparison operator | `GreaterThanThreshold` |
| Threshold | 0.05: AWS describes this as 5% of requests failing |

From the CloudWatch [recommended alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html) page. AWS applies the same 5% logic as the REST and HTTP client-error alarms; before relying on it, chart `Average`, `Sum` and `SampleCount` of `ClientError` together for your API to confirm the average behaves as a rate.

## Tuning for WebSocket traffic

WebSocket traffic is bursty in a way REST traffic is not: thousands of clients reconnect at once after a deploy or a network blip, and each reconnect that presents a stale token is a client error. That creates short, tall spikes.

- Keep the five-of-five window so a reconnect storm that clears in two minutes does not page you.
- If expired-token reconnects are routine, raise the threshold until a normal reconnect wave stays under it, and fix the client to refresh before reconnecting.
- Use per-route alarms (detailed metrics) for the routes that carry business messages, so a noisy `$connect` route does not mask them.
- Treat missing data as `notBreaching`.

## Create it

```
aws cloudwatch put-metric-alarm \
  --alarm-name chat-ws-prod-client-errors \
  --namespace AWS/ApiGateway \
  --metric-name ClientError \
  --dimensions Name=ApiId,Value=w1x2y3z4a5 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
```

## What to check when it fires

1. **Enable execution or access logging** on the stage and include `$context.routeKey`, `$context.eventType` and `$context.error.message`. The route key tells you whether failures are on `CONNECT` or on `MESSAGE` events.
2. **Connect failures:** invoke the authorizer with a real token and read its decision; check for a changed issuer, key rotation or a cached deny.
3. **Message failures:** confirm the clients' message shape still matches the route selection expression (for example `$request.body.action`).
4. **429s:** compare the message rate with your throttling settings; the re:Post article on [API Gateway 429 errors](https://repost.aws/knowledge-center/api-gateway-429-limit) applies.
5. **Connection drops** are covered in the re:Post guide to [WebSocket API errors](https://repost.aws/knowledge-center/api-gateway-websocket-error).

## Questions

### Is ClientError the same as 4xx for WebSocket APIs?

It plays the same role. WebSocket APIs report client-side failures as ClientError; the 4xx metric belongs to HTTP APIs and 4XXError to REST APIs.

### Can I alarm on ClientError per route?

Yes, if you enable detailed CloudWatch metrics on the stage. That adds a Route dimension so you can alarm on, for example, the sendmessage route on its own.

### Why do I get ClientError spikes after a deploy?

Clients reconnect when connections drop, and any that present expired tokens or old message formats fail at once. If the spike clears in a minute or two, it is usually reconnection noise.

## When this happens away from your desk

WebSocket problems tend to show up as a wave of reconnects, which looks alarming on a graph and may be harmless. CloudConsole, a phone app for AWS, is built to show the alarm with the route-level breakdown so you can tell the two apart from your phone.

[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)
- [Amazon API Gateway documentation](https://docs.aws.amazon.com/apigateway/)

## Related

- [CloudWatch alarm for API Gateway ExecutionError (WebSocket API)](https://cloudconsole.dev/alarms/api-gateway-executionerror)
- [CloudWatch alarm for API Gateway MessageCount (WebSocket API stage)](https://cloudconsole.dev/alarms/api-gateway-messagecount)
- [CloudWatch alarm for API Gateway IntegrationLatency (ApiId, Stage)](https://cloudconsole.dev/alarms/api-gateway-integrationlatency)
- [429 Too Many Requests from API Gateway](https://cloudconsole.dev/errors/api-gateway-429-too-many-requests)
- [403 Forbidden: User is not authorized to access this resource](https://cloudconsole.dev/errors/api-gateway-403-forbidden)
- [CloudWatch alarm for API Gateway 4xx (HTTP API)](https://cloudconsole.dev/alarms/api-gateway-4xx)

---

Source: https://cloudconsole.dev/alarms/api-gateway-clienterror

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