How can I troubleshoot API Gateway WebSocket API connection errors?

Short description

API Gateway WebSocket API connection errors might occur for the following reasons:

• 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

Resolution

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. To make a request to the backend, API Gateway must have the correct permissions for these resources. For more information, see Control and manage access to WebSocket APIs in API Gateway.

Also, make sure that you correctly configure the WebSocket API integration request.

Confirm that you send the request to the correct API ID, Region, and API stage

For your request, make sure that you verify the request information. In the following example request URL, make sure that the following fields are correct:

wss://a1b2c3d4e5.execute-api.us-east-1.amazonaws.com/production

• The WebSocket API ID is a1b2c3d4e5.
• The Region for the request is us-east-1.
• The API stage name production exists.

Check CloudWatch logs for errors

For more troubleshooting information, turn on Amazon CloudWatch logs for troubleshooting API Gateway WebSocket APIs. If you integrate a Lambda function for the backend, check the CloudWatch logs for errors. For more information, see Sending Lambda function logs to CloudWatch Logs.

Confirm that the API request is signed

If you turn on IAM authentication for the API method, then make sure that the API request is signed with Signature Version 4 (SigV4). For more information, see Create a signed AWS API request.

To turn on IAM authentication for your API Gateway API, complete the following steps:

1. In the API Gateway console, select your Websocket API.
2. Under Routes, choose $connect.
   Note: You can specify authorization settings only for the $connect route. The Authorization setting is applied to the entire API, not just the $connect route. The $connect route protects the other routes, Because the $connect route is called on for every connection, the $connect route protects all other routes.
3. Under Route request, under Route request settings, choose Edit.
4. For Authorization, choose AWS IAM from the dropdown list, and then choose Save changes.
5. For the changes to take effect, deploy your WebSocket API.

Related information

Monitor WebSocket API execution with CloudWatch metrics

Control access to WebSocket APIs with AWS Lambda REQUEST authorizers