# CloudWatch alarm for API Gateway ExecutionError (WebSocket API)

CloudWatch alarms · Updated 16 November 2026

**Short answer:** ExecutionError counts WebSocket messages where API Gateway could not successfully run the integration: a missing permission, a throttled or deleted Lambda function, or an integration failure. AWS recommends alarming on its Average per ApiId and Stage when it is above 0.05 for 3 of 3 one-minute periods.

## What makes ExecutionError different

A WebSocket API splits failures three ways. `ClientError` is the caller's fault, `IntegrationError` means your backend answered with an error, and `ExecutionError` means the call to the backend did not run properly in the first place. The last one is the closest WebSocket equivalent of a gateway-level 5xx, which is why AWS gives it the shorter three-minute window.

In practice it rises when:

- the Lambda integration is **throttled** because the account or function hit its concurrency limit;
- API Gateway lacks **permission to invoke** the function (a resource policy removed during a redeploy, or a new alias without `lambda:InvokeFunction` for `apigateway.amazonaws.com`);
- the integration target was **deleted or renamed**;
- an HTTP integration is unreachable or times out.

## Recommended settings

| Setting | Value |
|---|---|
| Namespace | `AWS/ApiGateway` |
| Metric | `ExecutionError` |
| Dimensions | `ApiId`, `Stage` |
| Statistic | `Average` |
| Period | 60 seconds |
| Datapoints to alarm | 3 |
| Evaluation periods | 3 |
| Comparison operator | `GreaterThanThreshold` |
| Threshold | 0.05: AWS frames this as execution errors on more than 5% of requests |

Settings from AWS's [recommended alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html) for API Gateway. As with `ClientError`, check how `Average` relates to `Sum` and `SampleCount` on your own API before you depend on it as a percentage.

## Tuning

Execution errors are rarely benign, so most teams should lower the threshold rather than raise it. A reasonable approach is to look at 14 days of data: if `ExecutionError` is flat at zero outside incidents, a threshold of 0.01 is safe and will catch a broken permission within three minutes. If you see a constant low level, find out why before tuning around it; it is often one route pointed at a function that no longer exists. Set missing data to `notBreaching`.

## Create it

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

Pair it with a Lambda `Throttles` alarm on the integration function so you can tell at a glance whether concurrency is the cause.

## Runbook

1. **Get the error text.** Turn on execution logging (`ERROR` level is enough) for the stage; each failed message logs why the integration call failed.
2. **Permission errors:** check the function's resource policy with `aws lambda get-policy --function-name chat-handler` and restore the statement that allows API Gateway to invoke it.
3. **Throttling:** look at `ConcurrentExecutions` and `Throttles` for the function. Reserved concurrency set too low on a busy route is a common culprit. See [Lambda TooManyRequestsException](https://cloudconsole.dev/errors/lambda-toomanyrequests-rate-exceeded).
4. **Missing target:** compare the integration URI in `aws apigatewayv2 get-integrations --api-id w1x2y3z4a5` with what exists.
5. For connection-level failures, the re:Post guide on [WebSocket API errors](https://repost.aws/knowledge-center/api-gateway-websocket-error) helps.

## Questions

### What is ExecutionError in API Gateway?

A WebSocket API metric counting messages where API Gateway failed to execute the integration, for example because of a permissions problem, Lambda throttling or a deleted target.

### How is ExecutionError different from IntegrationError?

IntegrationError means the backend ran and returned an error. ExecutionError means API Gateway could not run the backend call successfully at all.

### Why does the ExecutionError alarm use 3 datapoints instead of 5?

Execution failures affect every message on the broken route, so AWS shortens the window to catch them faster.

## When this happens away from your desk

A broken invoke permission can take a whole WebSocket feature down silently. CloudConsole, a phone app for AWS, is built to show the alarm, the integration's throttling metrics and the execution log lines together on a 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 ClientError (WebSocket API)](https://cloudconsole.dev/alarms/api-gateway-clienterror)
- [CloudWatch alarm for API Gateway IntegrationLatency (ApiId, Stage)](https://cloudconsole.dev/alarms/api-gateway-integrationlatency)
- [CloudWatch alarm: Lambda Throttles](https://cloudconsole.dev/alarms/lambda-throttles)
- [TooManyRequestsException: Rate Exceeded (Lambda throttling)](https://cloudconsole.dev/errors/lambda-toomanyrequests-rate-exceeded)
- [aws lambda add-permission](https://cloudconsole.dev/cli/lambda-add-permission)
- [CloudWatch alarm for API Gateway 4xx (HTTP API)](https://cloudconsole.dev/alarms/api-gateway-4xx)

---

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

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