Manipular erros do Lambda no API Gateway

Para integrações personalizadas do Lambda, você deve mapear erros retornados pelo Lambda na resposta de integração para respostas de erro HTTP padrão para os seus clientes. Caso contrário, os erros do Lambda serão retornados como respostas 200 OK por padrão, e o resultado não será intuitivo para os usuários da sua API.

Existem dois tipos de erros que o Lambda pode retornar: erros padrão e erros personalizados. Na sua API, você deve lidar com eles de maneira diferente.

Com a integração de proxy do Lambda, o Lambda precisa retornar uma saída com o seguinte formato:

{
  "isBase64Encoded" : "boolean",
  "statusCode": "number",
  "headers": { ... },
  "body": "JSON string"
}

Nessa saída, statusCode é normalmente 4XX para um erro de cliente e 5XX para um erro de servidor. O API Gateway lida com esses erros, mapeando o erro do Lambda para uma resposta de erro HTTP, de acordo com o statusCode especificado. Para que o API Gateway transmita o tipo de erro (por exemplo, InvalidParameterException) como parte da resposta ao cliente, a função do Lambda deve incluir um cabeçalho (por exemplo, "X-Amzn-ErrorType":"InvalidParameterException") na propriedade headers.

Manipule erros padrão do Lambda no API Gateway

Um erro do AWS Lambda padrão tem o seguinte formato:

{
  "errorMessage": "<replaceable>string</replaceable>",
  "errorType": "<replaceable>string</replaceable>",
  "stackTrace": [
    "<replaceable>string</replaceable>",
    ...
  ]
}

Aqui, errorMessage é uma expressão de string do erro. O errorType é um erro ou tipo de exceção que depende da linguagem. O stackTrace é uma lista de expressões de string que mostra o rastreamento de pilha que leva à ocorrência do erro.

Por exemplo, considere a seguinte função do Lambda do JavaScript (Node.js).

export const handler = function(event, context, callback) {
    callback(new Error("Malformed input ..."));
};

Essa função retorna o seguinte erro padrão do Lambda, contendo Malformed input ... como a mensagem de erro:

{
  "errorMessage": "Malformed input ...",
  "errorType": "Error",
  "stackTrace": [
    "export const handler (/var/task/index.js:3:14)"
  ]
}

Da mesma forma, considere a seguinte função do Lambda Python, que gera um Exception com a mesma mensagem de erro Malformed input ....

def lambda_handler(event, context):
    raise Exception('Malformed input ...')

Essa função retorna o seguinte erro padrão do Lambda:

{
  "stackTrace": [
    [
      "/var/task/lambda_function.py",
      3,
      "lambda_handler",
      "raise Exception('Malformed input ...')"
    ]
  ],
  "errorType": "Exception",
  "errorMessage": "Malformed input ..."
}

Observe que os valores de propriedade errorType e stackTrace são dependentes da linguagem. O erro-padrão também se aplica a qualquer objeto de erro que seja uma extensão do objeto Error ou uma subclasse da classe Exception.

Para mapear o erro padrão do Lambda para uma resposta de método, você deve primeiro decidir sobre um código de status HTTP para um determinado erro do Lambda. Depois, defina um padrão de expressão regular na propriedade selectionPattern do recurso IntegrationResponse associado ao código de status HTTP especificado. No console do API Gateway, este selectionPattern é indicado como regex de erro do Lambda na seção Resposta de integração, abaixo de cada resposta de integração.

nota

O API Gateway usa regexes de estilo padrão de Java para o mapeamento de resposta. Para obter mais informações, consulte Padrão na documentação do Oracle.

Por exemplo, para configurar uma nova expressão selectionPattern, usando a AWS CLI, chame o seguinte comando put-integration-response:

aws apigateway put-integration-response --rest-api-id z0vprf0mdh --resource-id x3o5ih --http-method GET --status-code 400 --selection-pattern "Malformed.*" --region us-west-2

Certifique-se de configurar também o código de erro correspondente (400) na resposta do método. Caso contrário, o API Gateway lançará uma resposta de erro de configuração inválida em tempo de execução.

nota

No tempo de execução, o API Gateway corresponde a errorMessage do erro do Lambda em relação ao padrão da expressão regular na propriedade selectionPattern. Se houver uma correspondência, o API Gateway retornará o erro do Lambda como uma resposta HTTP do código de status HTTP correspondente. Se não houver correspondência, o API Gateway retornará o erro como uma resposta padrão ou lançará uma exceção de configuração inválida se não houver uma resposta padrão configurada.

Definir o valor selectionPattern como .* para uma determinada resposta redefine essa resposta como a resposta padrão. Isso ocorre porque esse padrão de seleção corresponderá a todas as mensagens de erro, incluindo nulo, ou seja, qualquer mensagem de erro não especificado. O mapeamento resultante substitui o mapeamento padrão.

Para atualizar um valor selectionPattern existente usando a AWS CLI, chame a operação update-integration-response para substituir o valor do caminho /selectionPattern pela expressão regex especificada do padrão Malformed*​.

Para definir a expressão selectionPattern usando o console do API Gateway, digite a expressão na caixa de texto Regex de erro do Lambda ao configurar ou atualizar uma resposta de integração de um código de status HTTP especificado.

Manipule erros personalizados do Lambda no API Gateway

Em vez do erro padrão descrito na seção anterior, o AWS Lambda permite retornar um objeto de erro personalizado como uma string JSON. O erro pode ser qualquer objeto JSON válido. Por exemplo, a seguinte função do Lambda do JavaScript (Node.js) retorna um erro personalizado:

export const handler = (event, context, callback) => {
    ...
    // Error caught here:
    var myErrorObj = {
        errorType : "InternalServerError",
        httpStatus : 500,
        requestId : context.awsRequestId,
        trace : {
            "function": "abc()",
            "line": 123,
            "file": "abc.js"
        }
    }
    callback(JSON.stringify(myErrorObj));
};

Você deve transformar o objeto myErrorObj em uma string JSON antes de chamar callback para sair da função. Caso contrário, myErrorObj será retornado como uma string de "[object Object]". Quando um método da sua API é integrado com a função do Lambda anterior, o API Gateway recebe uma resposta de integração com a seguinte carga:

{
    "errorMessage": "{\"errorType\":\"InternalServerError\",\"httpStatus\":500,\"requestId\":\"e5849002-39a0-11e7-a419-5bb5807c9fb2\",\"trace\":{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}}"
}

Como ocorre com qualquer resposta de integração, é possível transmitir essa resposta de erro em seu estado inalterado como a reposta do método. Outra opção é fazer com que um modelo de mapeamento transforme a carga útil em um formato diferente. Por exemplo, considere o seguinte modelo de mapeamento de corpo para uma resposta de método do código de status 500:

{
    errorMessage: $input.path('$.errorMessage');
}

Esse modelo converte o corpo da resposta de integração que contém a string JSON no seguinte corpo de resposta de método. Esse corpo de resposta de método contém o objeto JSON de erro personalizado:

{
    "errorMessage" : {
        errorType : "InternalServerError",
        httpStatus : 500,
        requestId : context.awsRequestId,
        trace : {
            "function": "abc()",
            "line": 123,
            "file": "abc.js"
        }
    }
};

Dependendo dos requisitos da sua API, talvez você precise transmitir algumas das propriedades do erro personalizado, ou todas elas, como parâmetros de cabeçalho da resposta de método. Isso pode ser feito aplicando os mapeamentos de erros personalizados do corpo da resposta de integração aos cabeçalhos da resposta de método.

Por exemplo, a seguinte extensão do OpenAPI define um mapeamento das propriedades errorMessage.errorType, errorMessage.httpStatus, errorMessage.trace.function e errorMessage.trace para os cabeçalhos error_type, error_status, error_trace_function e error_trace, respectivamente.

"x-amazon-apigateway-integration": {
    "responses": {
        "default": {
          "statusCode": "200",
          "responseParameters": {
            "method.response.header.error_trace_function": "integration.response.body.errorMessage.trace.function",
            "method.response.header.error_status": "integration.response.body.errorMessage.httpStatus",
            "method.response.header.error_type": "integration.response.body.errorMessage.errorType",
            "method.response.header.error_trace": "integration.response.body.errorMessage.trace"
          },
          ...
        }
    }
}

Em tempo de execução, o API Gateway desserializa o parâmetro integration.response.body ao executar mapeamentos de cabeçalho. No entanto, essa desserialização aplica-se somente aos mapeamentos de corpo para cabeçalho de respostas de erro personalizado do Lambda, e não a mapeamentos de corpo para corpo usando $input.body. Com esses mapeamentos de corpo para cabeçalho de erro personalizado, o cliente recebe os seguintes cabeçalhos como parte da resposta de método, desde que os cabeçalhos error_status, error_trace, error_trace_function e error_type estejam declarados na solicitação do método.

"error_status":"500",
"error_trace":"{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}",
"error_trace_function":"abc()",
"error_type":"InternalServerError"

A propriedade errorMessage.trace do corpo da resposta de integração é uma propriedade complexa. Ela é mapeada para o cabeçalho error_trace como uma string JSON.