How do I find API Gateway REST API errors in my CloudWatch logs?

Resolution

CloudWatch provides two types of API logging, access logging and execution logging. For more information on the different types of API logging, see CloudWatch log formats for API Gateway.

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

Find a REST API request failure through CloudWatch access logs

Complete the following steps:

1. Set up CloudWatch API access logging through the API Gateway console.

2. Run the filter-log-events AWS CLI command on the API Gateway access logs. Use your preferred search utility.

   Note: the following filter-log-events command example uses the grep search utility for API Gateway access logs. Also, make sure that you replace the log-group-name with the access log group's name.

   aws logs filter-log-events --log-group-name 'API-Gateway-Access-Logs_2mg2xeej0a/test' | grep '17cb49b2-c061-11e9-bc30-f118c8b08d5f'

3. Check the response to your filter-log-events command to identify errors. The command response returns an object with all the $context variables that you mapped.

   The following is an example of a filter-log-events command response.

   {
      "requestId": "17cb49b2-c061-11e9-bc30-f118c8b08d5f",
       "ip": "1.2.3.4",
       "caller": "-",
       "user": "-",
       "requestTime": "28/Aug/2019:15:10:34 +0000",
       "httpMethod": "GET",
       "resourcePath": "/iam",
       "status": "403",
       "message": "Missing Authentication
               Token",
       "protocol": "HTTP/1.1",
       "responseLength": "42"
   }7

Find a REST API request failure through CloudWatch execution logs

Complete the following steps:

1. Set up CloudWatch API execution logging through the API Gateway console.
   Note: To prevent the storage of sensitive information, turn off Log full requests/responses data before moving to production.

2. Run the following cURL command to replicate the failed API request:
   Note: Replace abcd1234 with your API ID and us-east-1 with the AWS Region that your API is in.

   curl -X GET https://abcd1234.execute-api.us-east-1.amazonaws.com/dev/myapi -v

3. Note the x-amzn-requestid value in the API response headers. This value is required in the next step.

   The following is an example of API Gateway response headers.

   content-type: application/json
   < content-length: 41
   < x-amzn-requestid: 17cb49b2-c061-11e9-bc30-f118c8b08d5f
   < x-amz-apigw-id: eh7enHGIvHcFnPg=

Tracking API responses in the execution logs

1. Run the filter-log-events AWS CLI command on the API Gateway execution logs. Use your preferred search utility and the request ID to filter the results. This action returns the logs that are associated with that specific request ID.

   The following is a filter-log-events command that uses the grep search utility for API Gateway execution logs.

   Note: Replace log-group-name with the access log group's name.

   aws logs filter-log-events --log-group-name 'API-Gateway-Execution-Logs_2mg2xeej0a/test' | grep '17cb49b2-c061-11e9-bc30-f118c8b08d5f'

2. To identify errors, check the response to your filter-log-events command. The following are examples of the type of error messages that you might see:

   API Gateway permissions errors.

   (b59c91c8-3386-4478-b2b4-c4d63191756e) Execution failed due to configuration error: Invalid permissions on Lambda function(b59c91c8-3386-4478-b2b4-c4d63191756e) Gateway response type: DEFAULT_5XX with status code: 500
   (b59c91c8-3386-4478-b2b4-c4d63191756e) Gateway response body: {"message": "Internal server error"}

   API Gateway integration timeout errors.

   (2a1db04d-ac7c-463f-b9bd-478285467d58) Execution failed due to a timeout error(2a1db04d-ac7c-463f-b9bd-478285467d58) Gateway response type: DEFAULT_5XX with status code: 504
   (2a1db04d-ac7c-463f-b9bd-478285467d58) Gateway response body: {"message": "Endpoint request timed out"}

   API Gateway backend integration errors.

   (631ff793-2c5b-413d-a31d-f2cd3f75708b) Endpoint response body before transformations: {"errorMessage": "division by zero", "errorType": "ZeroDivisionError", "stackTrace": [" File \"/var/task/lambda_function.py\", line 7, in lambda_handler\n c=a/b\n"]}(631ff793-2c5b-413d-a31d-f2cd3f75708b) Lambda execution failed with status 200 due to customer function error: division by zero. Lambda request id: 7f0d8fc1-33ce-4bf9-8685-df78e179da5c
   (631ff793-2c5b-413d-a31d-f2cd3f75708b) Gateway response type: DEFAULT_5XX with status code: 502
   (631ff793-2c5b-413d-a31d-f2cd3f75708b) Gateway response body: {"message": "Internal server error"}

Can't get the request ID

1. Get either the HTTP status code or the returned error message, from the client-side application logs.

2. Run the filter-log-events AWS CLI command on the API Gateway access logs. Use the "grep" search utility for either the HTTP status code or the returned error message. The following are filter-log-events AWS CLI command examples:

   Filter-log-events command that uses the grep search utility for an HTTP status code.

   aws logs filter-log-events --log-group-name 'API-Gateway-Access-Logs_2mg2xeej0a/test' | grep '504'

   Filter-log-events command that uses the grep search utility for a returned error message from the client side.

   aws logs filter-log-events --log-group-name 'API-Gateway-Access-Logs_2mg2xeej0a/test' | grep 'Endpoint request timed out'

3. Find the request ID in the access logs results.

4. Follow the procedure in the Tracking API responses in the execution logs section of this article.