Error handling with API Gateway and Go Lambda functions

The API Gateway pattern relies on a facade/gated proxy service.
  • Consistent error responses, regardless of the error’s type or origin
  • Clear separation of external and internal interfaces
  • No leaking of private error details

Client facing errors

This is our API contract for error responses. The clients expect any non 2XX responses to contain an application/json body with this shape.

AWS API Gateway

Let’s investigate the request flow with AWS API Gateway and AWS Lambda. As we can see below, there are two sources for errors, the API Gateway itself (Gateway Responses) and the integration function (Integration Responses).

Errors can originate from various sources within a serverless application

Gateway responses

Gateway Responses represent errors that occur either before reaching the integration (such as access control errors, internal configuration errors, etc), or when the integration response cannot be mapped to a method response. These can be customised to fit our error schema by using a simple mapping template. Here’s the relevant section of our CloudFormation template.

Integration responses

The strategy for handling errors returned by a Lambda function is dependent on how the function is integrated with the endpoint, which can be done using either a proxy integration or a custom integration. The former proxies HTTP requests to the Lambda whereas the latter decouples the function from the original HTTP request further and completely relies on request and response mappings.

Lambda error responses

AWS Lambda uses its own error schema which can later be inspected and modified by API Gateway. This is why the following Lambda handler may not do what you expect.

The Lambda error response includes the actual type of the original error, see Go source, and the error value.
The error value is the JSON encoded structured error.
The handler does not control how this response will be processed by the gateway before being sent to the client.

Response mappings in API Gateway

A response received from the Lambda function then gets mapped by API Gateway in order to conform to our external API contract. To map errors we rely on integration response mappings, which use regular expressions, to match error codes.

Note that a 404 method response must also be defined for that endpoint.


The good news is that we were able to fulfil our error handling requirements using AWS API Gateway and Lambda, but we did find that some aspects of the solution have drawbacks.

One more thing: Integration testing with SAM Local

Full integration testing including all gateway mappings, validation, authorisers, etc. would have to be done in a testing CloudFormation stack. However, SAM Local helps considerably with testing the Lambda responses and gives us a sense of how our handler command will behave when executed in the real Lambda environment.




Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Sergio Garcez

Sergio Garcez

London based freelance software developer, interested in way too many things.