CloudConsole

CloudWatch alarm for API Gateway ExecutionError (WebSocket API)

Updated 16 November 2026 · How we write and check guides

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.

Chart of the ExecutionError alarm: Average per 1-minute period, ALARM when 3 of 3 datapoints are > 0.05
How the recommended alarm evaluates, with AWS's settings from this page. The metric values are illustrative.

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

SettingValue
NamespaceAWS/ApiGateway
MetricExecutionError
DimensionsApiId, Stage
StatisticAverage
Period60 seconds
Datapoints to alarm3
Evaluation periods3
Comparison operatorGreaterThanThreshold
Threshold0.05: AWS frames this as execution errors on more than 5% of requests

Settings from AWS's recommended alarms 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.
  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 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.

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

Sources