Let’s break down the issues here step by step—you’re missing a few key pieces that are preventing API Gateway from applying your response mappings correctly:

1. You’re likely using Lambda Proxy Integration (which ignores response templates) #

If your x-amazon-apigateway-integration has "type": "aws_proxy", that’s the root cause. Lambda Proxy Integration lets Lambda fully control the response status code and body, so any responses or responseTemplates configurations you define will be completely ignored.

To use custom response mappings, switch to non-proxy Lambda Integration by setting "type": "aws" instead. You’ll also need to add a requestTemplates section (even if it’s just passing the request through) and configure the Lambda invocation details (like uri pointing to your Lambda ARN).

2. Your regex pattern has incorrect escaping #

Your current regex ".*statusCode\\":400.*" has messed up escaping for the double quote in JSON. In JSON strings, a double quote needs to be escaped with a single backslash, so the correct pattern should be:

".*statusCode\":400.*"

For better reliability, you can make the regex more specific to match the full JSON structure, like:

"^\\{\"statusCode\":400,.*\\}$"

3. Your response template references $.errorMessage incorrectly #

The $input.path('$.errorMessage') only works if your Lambda throws an error (e.g., using callback(new Error(JSON.stringify({statusCode:400, message:"Invalid request parameters"})))).

If your Lambda is returning the JSON object directly (not throwing an error), the entire response is available at $input.path('$'). So your response template should be:

"application/json": "{ \"message\" : \"$input.path('$.message')\" }"

4. Missing passthroughBehavior setting #

Add "passthroughBehavior": "never" to your x-amazon-apigateway-integration configuration. This forces API Gateway to use your defined response templates instead of falling back to passing the raw Lambda response when a pattern isn’t matched (which is why you’re seeing the full raw response with a 200 status code).

5. You need to define the 400/500 responses in your OpenAPI top-level responses #

API Gateway requires explicit definition of allowed status codes in the OpenAPI’s operation-level responses section. For example:

"responses": {
  "400": {
    "description": "Bad Request",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string"
            }
          }
        }
      }
    }
  },
  "500": {
    "description": "Internal Server Error",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Putting it all together, your corrected x-amazon-apigateway-integration might look something like this (for non-proxy integration):

"x-amazon-apigateway-integration": {
  "type": "aws",
  "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/your-lambda-arn/invocations",
  "httpMethod": "POST",
  "requestTemplates": {
    "application/json": "{ \"body\": $input.json('$') }"
  },
  "passthroughBehavior": "never",
  "responses": {
    ".*statusCode\":400.*": {
      "statusCode": "400",
      "responseTemplates": {
        "application/json": "{ \"message\" : \"$input.path('$.message')\" }"
      }
    },
    ".*statusCode\":500.*": {
      "statusCode": "500",
      "responseTemplates": {
        "application/json": "{ \"message\" : \"$input.path('$.message')\" }"
      }
    }
  }
}

Don’t forget to deploy your API Gateway changes after updating the OpenAPI definition—changes won’t take effect until you push a new deployment.

内容的提问来源于stack exchange，提问作者Nikhil Badami