How can I troubleshoot API Gateway WebSocket API connection errors?

3 minute read

I tried to connect to my Amazon API Gateway WebSocket API but I received errors. How do I troubleshoot my WebSocket API connection?

Short description

API Gateway WebSocket API connection errors might occur due to:

  • Insufficient permissions to make the request to the backend
  • Incorrect fields for the API ID, AWS Region, and API stage
  • Errors in the backend integration
  • AWS Identity and Access Management (IAM) authentication errors


Follow these troubleshooting steps for your use case.

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

API Gateway uses IAM roles, policies, tags, and AWS Lambda authorizers to control access to a WebSocket API. For more information, see Controlling and managing access to a WebSocket API in API Gateway.

Also, make sure that the WebSocket API integration request is configured correctly.

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

In this example request URL, make sure that the following fields are correct:

  • The WebSocket API ID "a1b2c3d4e5".
  • The AWS Region "us-east-1".
  • The API stage name "production" exists.

Check CloudWatch logs for errors

Follow the instructions to turn on Amazon CloudWatch logs for troubleshooting API Gateway WebSocket APIs. If a Lambda function is integrated for the backend, check the CloudWatch logs for errors. For more information, see Accessing CloudWatch logs for AWS Lambda.

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

If IAM authentication is turned on, then make sure that the API request is signed with Signature Version 4 (SigV4). For more information, see Signing AWS requests with Signature Version 4.

To turn on IAM authentication for your API Gateway API, follow these steps:

  1. In the API Gateway console, choose the name of your API.
  2. In the Resources pane, choose a method (such as GET or POST) that you want to activate IAM authentication for.
  3. In the Method Execution pane, choose Method Request.
  4. Under Settings, for Authorization, choose the pencil icon (Edit). Choose AWS_IAM from the dropdown list, and then choose the check mark icon (Update).
  5. (Optional) Repeat steps 2-4 for each API method that you want to activate IAM authentication for.
  6. Deploy your WebSocket API for the changes to take effect.

Related information

Monitoring WebSocket API execution with CloudWatch metrics

Use API Gateway Lambda authorizers

How do I troubleshoot HTTP 403 Forbidden errors when using a Lambda authorizer with an API Gateway REST API?

How do I troubleshoot issues when connecting to an API Gateway private API endpoint?

AWS OFFICIALUpdated 10 months ago