How can I use a SAW runbook to troubleshoot API Gateway HTTP invoke errors?

3 minute read

I want to troubleshoot Amazon API Gateway errors using the AWSSupport-TroubleshootAPIGatewayHttpErrors AWS Support Automation Workflow (SAW) runbook.

Short Description

The AWSSupport-TroubleshootAPIGatewayHttpErrors runbook provides an automated solution to find and troubleshoot errors that arise from API Gateway HTTP requests. When your API is configured to log all resource and method requests, you can use this runbook to troubleshoot 4xx and 5xx errors.

For more information on how to set up logging, see Setting up CloudWatch logging for a REST API in API Gateway.

For more information on SAW, see AWS Support Automation Workflows (SAW).


The AWSSupport-TroubleshootAPIGatewayHttpErrors runbook validates the API, resource, method, and stage before attempting to retrieve and analyze Amazon CloudWatch Logs.

The current user or assumed AWS Identity and Access Management (IAM) service role that runs the automation must have the following permissions:

  • apigateway:GET
  • logs:GetQueryResults
  • logs:StartQuery
  • ssm:DescribeAutomationExecutions
  • ssm:GetAutomationExecution
  • ssm:DescribeAutomationStepExecutions
  • ssm:StartAutomationExecution
  • ssm:DescribeDocument
  • ssm:GetDocument
  • ssm:ListDocuments


Before running the runbook, make sure that your IAM user or role has the correct permissions. These permissions include specific AWS Systems Manager permissions and the additional services-specific permissions covered in earlier sections of this article.

Run the AWSSupport-TroubleshootAPIGatewayHttpErrors automation

  1. Open the AWSSupport-TroubleshootAPIGatewayHttpErrors runbook.
    Note: The runbook is in the us-east-1 AWS Region.

  2. Select Execute automation.

    For input parameters, enter the following:

    • RestApiId (required): The API ID for the API that requires troubleshooting.
    • StageName (required): The name of the deployed stage.
    • ResourcePath (required): The method's resource path.
    • HttpMethod (required): The method for the configured resource path.
    • StartTime (required): The start date and time for querying the CloudWatch Logs. The format must be yyyy-MM-ddTHH:mm:ss and the time zone must be UTC.
    • EndTime (required): The end date and time for querying the CloudWatch Logs. The format must be yyyy-MM-ddTHH:mm:ss and the time zone must be UTC.
    • AccessLogs (required): Provide information about whether access logs are analyzed.
    • ExecutionId (optional): The execution ID for the request that experiences errors.
    • AutomationAssumeRole (optional): The Amazon Resource Name (ARN) of the IAM role that allows Automation, a capability of Systems Manager, to perform the actions on your behalf. If no role is specified, then Automation uses the permissions of the user that starts the runbook.
  3. Select Execute. The automation initiates.

  4. After the automation finishes, review the Outputs section for detailed results.

Note: The runbook completes successfully, even if no logs are found.