In order to properly troubleshoot issues in serverless architectures built with API Gateway and AWS Lambda, it's useful to be aware of API Gateway's default failure modes when configured with a Lambda authorizer and a Lambda proxy integration.
Note: This post refers to API Gateway's default failure modes because Gateway responses allow to customize HTTP responses sent by API Gateway for certain failures.
A Lambda authorizer must return a Lambda authorizer output with at least a policyDocument (other fields are optional) in to evaluate the request against.
The policy evaluation can have one of the following results:
| Result | Description | Response status code | Response body |
|---|---|---|---|
ALLOW |
The HTTP request matches at least one ALLOW statement in the policy and does not match any DENY statements. |
(Depends on API Gateway integration) | (Depends on API Gateway integration) |
EXPLICIT_DENY |
The HTTP request matches at least one DENY statement in the policy. |
403 |
{ "Message": "User is not authorized to access this resource with an explicit deny" } |
IMPLICIT_DENY |
The HTTP request does not match any statements in the policy. | 403 |
{ "Message": "User is not authorized to access this resource" } |
Note: There are two types of Lambda authorizers: REQUEST and TOKEN. This post focuses on REQUEST Lambda authorizers, so your mileage may vary for TOKEN Lambda authorizers.
An HTTP request sent to an API Gateway instance configured with a REQUEST Lambda authorizer and a Lambda proxy integration can fail due to one or more of the following reasons:
| Error | Description | Lambda error | APIGW status code | APIGW body |
|---|---|---|---|---|
AUTHORIZER_APIGW_ID_SRC_MISSING |
The request has a missing, null or empty REQUEST Lambda authorizer identity source value. |
- | 401 |
{ "message": "Unauthorized" } |
AUTHORIZER_APIGW_TIMEOUT |
API Gateway times out while waiting for the Lambda authorizer invocation to complete. | No |
500 |
{ "message": null } |
AUTHORIZER_ERROR_OTHER |
The Lambda authorizer returns an invocation error with errorMessage set to anything other than "Unauthorized". |
Yes |
500 |
{ "message": null } |
AUTHORIZER_ERROR_UNAUTHORIZED |
The Lambda authorizer returns an invocation error with errorMessage set to "Unauthorized". |
Yes |
401 |
{ "message": "Unauthorized" } |
AUTHORIZER_INVOKE_DENIED |
API Gateway or the configured API Gateway IAM Role is not authorized to invoke the Lambda authorizer. | - | 500 |
{ "message": null } |
AUTHORIZER_LAMBDA_TIMEOUT |
The Lambda function execution exceeds the configured Lambda timeout. | Yes |
500 |
{ "message": null } |
AUTHORIZER_RESPONSE_INVALID |
The Lambda authorizer returns an invocation response that does not conform to the Lambda authorizer output. | No |
500 |
{ "message": null } |
PROXY_INTEG_APIGW_TIMEOUT |
API Gateway integration timeout elapses before the Lambda proxy integration invocation finishes. | No |
504 |
{ "message": "Endpoint request timed out" } |
PROXY_INTEG_ERROR |
The Lambda proxy integration returns an invocation error. | Yes |
502 |
{ "message": "Internal server error" } |
PROXY_INTEG_INVOKE_DENIED |
API Gateway or the configured API Gateway IAM Role is not authorized to invoke the Lambda proxy integration. | - | 500 |
{ "message": "Internal server error" } |
PROXY_INTEG_LAMBDA_TIMEOUT |
The Lambda proxy integration exceeds the configured Lambda timeout before the integration timeout elapses. | Yes |
502 |
{ "message": "Internal server error" } |
PROXY_INTEG_RESPONSE_INVALID |
The Lambda proxy integration returns an invocation response that does not conform to the Lambda proxy output. | No |
502 |
{ "message": "Internal server error" } |
Note: API Gateway can invoke a Lambda function directly or through an API Gateway IAM Role.
In order to prevent *_INVOKE_DENIED errors, if don't use a role, make sure to properly configure a resource-based policy allowing API Gateway to invoke each Lambda function.
Warning: When a Lambda authorizer returns an "Unauthorized" invocation error, even though API Gateway responds with a 401, the Lambda service increments the Lambda Errors metric which may trigger a CloudWatch "false alarm".
Warning: The AUTHORIZER_APIGW_TIMEOUT timeout cannot be explicitly configured and it's not publicly documented.
However, manual tests of this have determined that it's 30 seconds.
As a result, you should configure the Lambda authorizer's Lambda timeout to be 29 seconds or less so that:
- The Lambda authorizer does not continue executing (and getting charged) in order to produce a response that would be ignored by API Gateway.
- Lambda authorizer timeouts can be unambiguously distinguished from other failures.
Top comments (0)