How can I use API Gateway logs to troubleshoot API issues?

Short description

To troubleshoot an API Gateway REST API or WebSocket API, turn on execution logging, and then use Amazon CloudWatch Logs to access your logs. Make sure that you attach all the required permissions to the API Gateway AWS Identity and Access Management (IAM) role. For instructions, see How do I turn on CloudWatch Logs to troubleshoot my API Gateway REST API or WebSocket API?

Note: HTTP APIs support only access logging. For more information on how to configure logging for these APIs, see Configure logging for HTTP APIs in API Gateway.

Resolution

After you turn on logging, API Gateway automatically creates a CloudWatch log group named API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}. Use this group to further troubleshoot your issues. For more information, see CloudWatch log formats for API Gateway.

Check for authorization errors

If you turn on AWS Lambda authorizers for your API, then the logs indicate if the request is authorized and include authorizer and request IDs.

Example authorized logs:

Starting authorizer: 62mgrc for request: 3323ffe5-6ddf-45c8-896a-b45ec2284cc0
Successfully completed authorizer execution

Example unauthorized logs:

Starting authorizer: 62mgrc for request: fd443056-60d0-425f-874e-e93e5d61351e  
Unauthorized request: fd443056-60d0-425f-874e-e93e5d61351e

To troubleshoot this issue, see Why do I get API Gateway "401 Unauthorized" errors after I create a Lambda authorizer?

Update your usage plan configuration

After the Lambda authorizer logs, API Gateway verifies the usage plan for the API request. If you haven't configured a usage plan, then API requests aren't counted towards throttling limits.

Example usage plan logs:

Verifying Usage Plan for request: 3323ffe5-6ddf-45c8-896a-b45ec2284cc0. API Key: API Stage: <api_id>/<stage>
API Key authorized because method 'GET /' does not require API Key. Request will not contribute to throttle or quota limits
Usage Plan check succeeded for API Key and API Stage <api_id>/<stage>

If you configure APIs with API keys and the X-API-Key header is missing, then the logs return an error similar to the following message:

"API Key not authorized because method 'GET /' requires API Key and API Key is not associated with a Usage Plan for API Stage <api_id>/<stage>: API Key was required but not present"

To resolve this issue, review the API configuration. You must associate the API key with the required usage plan and you must include the key in the request as X-API-KEY header with the correct value.

If you add the correct API key in the header and API Gateway throttles the request, then the logs return an error similar to the following message:

"API Key **FGQes7 exceeded throttle limit for API Stage <api_id>/<stage>: Key throttle limit exceeded for Usage Plan ID iwuzkt. Limit: 5.00 Burst: 0
Method completed with status: 429"

To resolve this issue, complete the steps in How can I troubleshoot "429 Too Many Requests" or "Limit Exceeded" errors for my API with API Gateway?

Request log types

When you turn on data tracing and error and info logs, the API Gateway logs contain more details to help you troubleshoot. To find out where the API Gateway request fails, review the following log types for more information.

Note: For request logs, you must choose Errors and info logs from the CloudWatch logs dropdown menu. Then, turn on Data tracing for the execution logs. Because data tracing can log sensitive data, it's not a best practice to turn on Data tracing for production APIs.

Method request logs

Method request logs include detailed information that an API request receives, including the request path, query parameter, request header, and request body.

Example method request log:

(####) Method request path: {...}
(####) Method request query string: {...}
(####) Method request headers: {User-Agent=...}
(####) Method request body before transformations: ...

Endpoint request logs

Endpoint request logs include detailed information that an API request receives, including the URI, request headers, and request body.

Example endpoint request log:

(####) Endpoint request URI: ...
(####) Endpoint request headers: {...}
(####) Endpoint request body after transformations: {...}

The data included in endpoint requests are sent to your backend integration for further processing.

Endpoint response logs

Endpoint response logs include the data that the backend integrations returns, including the status code, headers, body, and Integration latency.

Example endpoint response log:

(####) Received response. Status: YYY, Integration latency: ZZZ ms
(####) Endpoint response headers: {...}
(####) Endpoint response body before transformations: {...}

Method response logs

Method response logs include the headers and body sent to the client after the transformation.

Example method response log:

(####) Method response body after transformations: ...
(####) Method response headers: {...}

Important: API Gateway limits log events to 1024 bytes. API Gateway truncates log events larger than 1024 bytes, such as request and response bodies, before the logs are submitted to CloudWatch logs.

Related information

How do I troubleshoot missing CloudWatch logs for API Gateway REST APIs?

Set up CloudWatch logging for REST APIs in API Gateway

Monitor REST API execution with Amazon CloudWatch metrics

Monitor WebSocket API execution with CloudWatch metrics

Troubleshooting Amazon API Gateway with enhanced observability variables