How do I map the response status codes for API Gateway integrations in HTTP APIs?

3 minute read

What are the differences between payload versions 1.0 and 2.0? How do I map the status codes returned by HTTP APIs in Amazon API Gateway? -or- How do I map the status codes in HTTP APIs?


When you want to override your backend response status codes, use API Gateway mapping templates or regular expressions to map the status codes. You can do this in proxy and non-proxy integrations with HTTP API.

Working with HTTP APIs

HTTP APIs are different in design when compared to REST APIs. HTTP APIs are integrated by default proxy and return the same response. Unlike REST APIs, HTTP APIs provide two payload format versions to use with Lambda integration. For the 1.0 and 2.0 payload format versions, there are associated Lambda function response formats.

When the payload format version 2.0 is used, if the Lambda function doesn’t explicitly pass the status code in a valid JSON response, API Gateway assumes the following:

  • IsBase64Encoded is false
  • statusCode is 200
  • content-type is application/json
  • body is the response from a Lambda function

In the previous example, the HTTP API doesn’t return any errors, but forwards the assumed status code 200.

When the payload format version 1.0 is used, the Lambda integration must return a response in the following format. API Gateway doesn’t make assumptions of the response and returns a 500 error.

    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headername": "headervalue", ... },
    "multiValueHeaders": { "headername": ["headervalue", "headervalue2", ...], ... },
    "body": "..."

Mapping status codes

To map the status code to a static value basing on the returned back-end response key:

  1. Navigate to the integrations configured in HTTP API.
  2. Choose the Integration route to modify. Choose Manage Integration. Scroll to the parameter mapping, and then choose Create parameter mapping.
  3. Set Mapping type to Response (based on a status code). Also set Response status code because the integration responses that match this status code must have parameter mapping applied.
  4. Choose Add new mapping.
  5. Under Parameter to modify, choose statusCode. Set the Modification type to Overwrite.
  6. Set Value to Static value.
    Note: This value needs to be sent to the client.
  7. Choose Create.

Related information

Working with models and mapping templates

Transforming API requests and responses

AWS OFFICIALUpdated 2 years ago