How can I use Amazon API Gateway logs for troubleshooting?

Last updated: 2022-12-07

I want to use Amazon API Gateway logs for troubleshooting API issues.

Short description

To troubleshoot an API Gateway REST API or WebSocket API, turn on execution logging and access logging using Amazon CloudWatch Logs. Make sure that you have attached 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 for troubleshooting my API Gateway REST API or WebSocket API?

Note: HTTP APIs currently support access logging only, and logging setup is different for these APIs. For more information, see Configuring logging for an HTTP API.

Resolution

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

AWS Lambda authorizers

If you have Lambda authorizers turned on for your API, the logs indicate if the request is authorized and include the 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

Usage plans

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 for 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 have configured APIs with API keys but the X-API-Key header is missing, then the logs return an error similar to the following:

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

If you added the correct API key in the header but the request is throttled, then the logs return an error similar to the following:

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

Request log types

Note: All request log types require turning on Log full requests/responses data in the execution logs.

Method request logs

Method request logs includes detailed information received by an API request including the request path, query parameter, request header, and request body.

Endpoint request logs

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

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

Endpoint response logs

Endpoint response logs include the data returned by the backend integration including the status code, headers body, and Integration latency.

Method response logs

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

Important: API Gateway limits log events to 1024 bytes. Log events larger than 1024 bytes, such as request and response bodies, are truncated by API Gateway before submission to CloudWatch logs.

Related information

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

Setting up CloudWatch logging for a REST API in API Gateway

Monitoring REST API execution with Amazon CloudWatch metrics

Monitoring WebSocket API execution with CloudWatch metrics

Did this article help?

Submit feedback

Do you need billing or technical support?

Contact AWS Support

How do I integrate an API Gateway REST API with Amazon SQS and resolve common errors?

Last updated: 2022-11-23

I want to integrate an Amazon API Gateway REST API with Amazon Simple Queue Service (Amazon SQS). I also want to troubleshoot integration errors. What steps do I take?

Resolution

Users configure API Gateway REST APIs so that they work with Amazon SQS to create an integrated solution. This article provides steps to integrate API Gateway with Amazon SQS and information to troubleshoot common setup errors.

Set up REST API and an Amazon SQS integration

To integrate an API Gateway REST API with Amazon SQS, follow these steps:

1. Create an SQS queue.

2. Create an AWS Identity and Access Management (IAM) role, and then attach an Amazon SQS policy with a SendMessage permission. This policy allows messages from the API to be published to Amazon SQS. In the policy, replace example-region with your AWS Region, example-account-id with your AWS account ID, and example-sqs-queue-name with your SQS queue name.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Resource": [
        "arn:aws:sqs:example-region:example-account-id:example-sqs-queue-name"
      ],
      "Action": [
        "sqs:SendMessage"
      ]
    }
  ]
}

3. Create a REST API in API Gateway.

4. In the API Gateway console, create an Amazon SQS integration for your newly created REST API.

Optionally, create a REST API resource or a REST API method.
Create a POST method.
For Integration type , choose AWS Service .
For AWS Region , choose your AWS Region.
For AWS Service , choose Simple Queue Service (SQS) .
For AWS Subdomain , enter Optional .
For HTTP method , choose POST .
For Action Type , choose Use path override .
For Path override (optional) , enter example-account-id/example-sqs-queue-name where you replace example-account-id with your AWS account ID and example-sqs-queue-name with your SQS queue name. For example, 1234567890/MySQSStandardQueue.
For Execution role , enter the ARN of the IAM role created in step 2 .
For Content Handling , choose the option that fits your setup.
Clear or select Default Timeout . Choose the option that fits your setup.
Save the new POST method.
Continue entering your REST API integration information.
Choose the POST method Integration Request .
Expand HTTP Headers .
Choose Add header .
For Name , enter Content-Type .
For Mapped from , enter 'application/x-www-form-urlencoded' and choose Create .
Expand Mapping Templates .
For Request body passthrough , select the option that fits your requirements.
Choose Add mapping template .
For Content-Type , enter application/json and choose Create .
For the template, enter Action=SendMessage&MessageBody=$input.body

4. Deploy the configured REST API.

5. Test the setup by sending the following request to API Gateway. Replace example-api-id with your API ID, example-region with your AWS Region, example-stage with your testing stage name, and example-resource with your resource name.

curl --location --request POST 'https://example-api-id.execute-api.example-region.amazonaws.com/example-stage/example-resource' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "message": "Hello World"
    }'

When your integration is successful, your response looks similar to the following:

{
    "SendMessageResponse": {
        "ResponseMetadata": {
            "RequestId": "f879fb11-e736-52c0-bd29-a0f2d09ad90d"
        },
        "SendMessageResult": {
            "MD5OfMessageAttributes": null,
            "MD5OfMessageBody": "3fc759ac1733366f98ec4270c788fcd1",
            "MD5OfMessageSystemAttributes": null,
            "MessageId": "4c360c3c-08f4-4392-bc14-8b0c88e314a2",
            "SequenceNumber": null
        }
    }
}

Resolving common errors

UnknownOperationException error

An UnknownOperationException error occurs when a user fails to configure the Content-Type as "application/x-www-form-urlencoded" in the integration request HTTP header. The UnknownOperationException error also occurs when the SendMessage action isn’t added to the integration request mapping template.

AccessDenied error

The following is an example of an AccessDenied error:

{
  "Error": {
    "Code": "AccessDenied",
    "Message": "Access to the resource https://sqs.example-region.amazonaws.com/example-account-id/example-sqs-queue-name is denied.",
    "Type": "Sender"
  },
  "RequestId": "92aea8b7-47f1-5bd4-b3c4-f3d0688d3809"
}

An AccessDenied error occurs when the API integration execution role doesn’t have the sqs:SendMessage permission set to send messages to the SQS queue. The AccessDenied error can also occur when special characters such as "&" and "%" are passed in the request body payload. The special characters must be encoded to pass. Add the $util.urlEncode() function in the mapping template to convert the request body from a string to an encoded format. The following is an example mapping template:

Action=SendMessage&MessageBody=$util.urlEncode($input.body)

The following example includes the permissions needed to send messages to the SQS queue. Replace example-region with your AWS Region, example-account-id with your AWS account ID, and example-sqs-queue-name with your SQS queue name.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Resource": [
        "arn:aws:sqs:example-region:example-account-id:example-sqs-queue-name"
      ],
      "Action": [
        "sqs:SendMessage"
      ]
    }
  ]
}

KMS.AccessDeniedException error

The following are two examples of KMS.AccessDeniedException errors:

{
  "Error": {
    "Code": "KMS.AccessDeniedException",
    "Message": "User: arn:aws:sts::example-account-number:assumed-role/example-sqs-queue-name/BackplaneAssumeRoleSession is not authorized to perform: kms:GenerateDataKey on resource: arn:aws:kms:example-region:example-account-number:key/example-keyId because no identity-based policy allows the kms:GenerateDataKey action (Service: AWSKMS; Status Code: 400; Error Code: AccessDeniedException; Request ID: c58f1eec-6b18-4029-826b-d05d6a715716; Proxy: null)",
    "Type": "Sender"
  },
  "RequestId": "99976a6a-3311-57e9-86e9-310d0654ff80"
}

{
  "Error": {
    "Code": "KMS.AccessDeniedException",
    "Message": "The ciphertext refers to a customer master key that does not exist, does not exist in this region, or you are not allowed to access. (Service: AWSKMS; Status Code: 400; Error Code: AccessDeniedException; Request ID: a8adea02-c246-49d9-8b3d-ff6b6a43b40f; Proxy: null)",
    "Type": "Sender"
  },
  "RequestId": "9565c451-742c-55f3-a1eb-9f3641fd30aa"
}

A KMS.AccessDeniedException error occurs when the API integration execution role can’t perform operations through AWS Key Management Service (AWS KMS). Permission must be configured to perform operations on the AWS KMS keys that are attached to the Amazon SQS server-side encrypted queue.

The following example includes the permissions needed to perform operations on the KMS keys attached to the SQS queue. Replace example-account-id with your AWS account ID, and example-api-gw-integration-execution-role with your execution role name.

{
  "Sid": "Allow use of the key",
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::example-account-id:role/example-api-gw-integration-execution-role"
  },
  "Action": [
    "kms:Encrypt",
    "kms:GenerateDataKey*",
    "kms:Decrypt"
  ],
  "Resource": "*"
}

Did this article help?

Submit feedback

Do you need billing or technical support?

Contact AWS Support

API	Example	Stage	Path	Default URL	Custom Domain URL
abcd3456ef	API 1	dev	(none)	https://abcd3456ef.execute-api.us-east-1.amazonaws.com/dev	https://api.example.com
wxyz1234ab	API 2	test	orders	https://wxyz1234ab.execute-api.us-east-1.amazonaws.com/test	https://api.example.com/orders
mnop5678qr	API 3	prod	customers	https://mnop5678qr.execute-api.us-east-1.amazonaws.com/prod	https://api.example.com/customers

Welcome to Knowledge Base!

KB at your finger tips

Cloud-AWS

Troubleshoot API Gateway logs

How can I use Amazon API Gateway logs for troubleshooting?

Short description

Resolution

AWS Lambda authorizers

Usage plans

Request log types

Related information

Troubleshoot API Gateway SSL errors

How can I troubleshoot the API Gateway error “Execution failed due to configuration error: General SSLEngine problem”?

Resolution

A supported CA

A valid ACM certificate that isn't expired

A valid CA certificate

A certificate that doesn't exceed 2048 bits

Related information

Forward host headers for an API Gateway REST API

How can I forward the host header with private integration for an API Gateway REST API?

Short description

Resolution

Create an API Gateway REST API

Configure your API's method request and Integration request

Deploy your API to a new stage

Related information

How do I integrate an API Gateway REST API with Amazon SQS and resolve common errors?

How do I integrate an API Gateway REST API with Amazon SQS and resolve common errors?

Resolution

Set up REST API and an Amazon SQS integration

Resolving common errors

Troubleshoot API Gateway WebSocket API connection errors

How can I troubleshoot API Gateway WebSocket API connection errors?

Short description

Resolution

Confirm that the WebSocket API has the required permissions to make a request to the backend

Confirm that the request is sent to the correct API ID, AWS Region, and API stage

Check CloudWatch logs for errors

Confirm that the API request is signed if the API method has IAM authentication turned on

Related information

Troubleshoot 403 "missing authentication token" errors for API Gateway APIs with custom domain names

How can I troubleshoot 403 "missing authentication token" errors when invoking API Gateway REST or HTTP APIs with a custom domain name?

Short description

Resolution

Related information