CloudConsole

API Gateway 5xx errors with Logs Insights

Updated 16 November 2026 · How we write and check guides

Short answer

With JSON access logging enabled, query the stage's access log group with filter status >= 500 and group by route and status to see which endpoints are failing and how. For the reason behind each failure, add the integration error message to the access log, or search the REST API execution logs for "Method completed with status: 5".

Logs Insights query: filter status >= 500 | stats count(*) as errors, latest(erro…; result columns method, path, status…
The query from this page and the shape of the table it returns. Copy the query from the text below.

The query

Assuming an access log format along these lines (numbers unquoted so they stay numeric):

{"requestId":"$context.requestId","ip":"$context.identity.sourceIp","method":"$context.httpMethod","path":"$context.resourcePath","status":$context.status,"latency":$context.responseLatency,"integrationStatus":"$context.integrationStatus","error":"$context.error.message","integrationError":"$context.integrationErrorMessage"}

this query lists the failing routes:

filter status >= 500
| stats count(*) as errors, latest(error) as lastError, latest(integrationError) as lastIntegrationError by method, path, status
| sort errors desc
| limit 50

How it works

  1. filter status >= 500 keeps server-side failures. Because the access log is JSON, Logs Insights discovers status as a number.
  2. stats … by method, path, status gives one row per route and status code, so a single broken endpoint stands out from general noise.
  3. latest(error) and latest(integrationError) attach the most recent API Gateway error message and integration error to each row, which usually names the cause directly.
  4. sort errors desc puts the worst routes first.

For HTTP APIs, use $context.routeKey in the log format instead of resourcePath.

What the 5xx codes usually mean

StatusTypical causeDetail
500API Gateway couldn't run the integration: missing invoke permission, bad mapping template, misconfigured authoriserExecution log: Execution failed due to configuration error
502Integration returned something API Gateway couldn't use, often a Lambda proxy response in the wrong shape, or the function threwMalformed Lambda proxy response
503Backend unavailableCheck the target's health and any network path
504Integration didn't respond in time (29 seconds by default for REST APIs)Endpoint request timed out

A status in the access log comes from API Gateway; integrationStatus is what the backend returned. A 502 with an integration status of 200 points at the response format, not the backend logic.

Variations

5xx over time, to see when the failures started and whether they correlate with latency:

filter status >= 500
| stats count(*) as errors, avg(latency) as avgLatencyMs by bin(5m)

Run the same query without the filter to get total requests per bucket for comparison.

REST API execution logs, when access logs aren't set up:

filter @message like /Method completed with status: 5/
| parse @message /^\((?<reqId>[^)]+)\) Method completed with status: (?<status>\d+)/
| stats count(*) as n by status

Then search the same group for one reqId to read its full execution trace, including the endpoint response body.

Client-facing errors that aren't 5xx, such as Missing Authentication Token, show up as 403s; see missing authentication token.

Limits and cost

Execution logging at INFO level is very verbose and costs both ingestion and query scanning; switch it on while investigating and back to ERROR or off afterwards. Access logs are the cheaper long-term source. For alerting, use the 5XXError metric (see API Gateway 5XXError alarm) and keep these queries for diagnosis.

Questions

How do I see API Gateway errors in CloudWatch?

Enable access logging (and execution logging for REST APIs) on the stage, then query the log group in Logs Insights with filter status >= 500.

What are the API Gateway error codes?

4xx codes are client errors such as 403 and 429; 5xx are server-side: 500 configuration errors, 502 bad integration responses, 503 unavailable backends and 504 integration timeouts.

What does 'Network error communicating with endpoint' mean?

API Gateway couldn't reach the backend at the network level, for example through a VPC link or to a private endpoint. Check connectivity and target health.

When this happens away from your desk

API 5xx alarms are exactly the kind that fire while you're commuting. CloudConsole, a phone app for AWS, is built to show the alarm and the failing routes on your phone.

About the app → · Download on the App Store

Sources