Como posso solucionar erros de invocação HTTP do API Gateway?

Resolução

Para solucionar erros 5xx das APIs REST que você configurou para registrar solicitações de recursos e operações, use o runbook AWSSupport-TroubleshootAPIGatewayHTTPErors.

Ou é possível solucionar manualmente os erros 5xx.

Observação: Se você receber erros ao executar comandos da AWS Command Line Interface (AWS CLI), consulte Solução de problemas da AWS CLI. Além disso, verifique se você está usando a versão mais recente da AWS CLI.

Use o runbook automatizado para solucionar erros

Antes que o runbook AWSSupport-TroubleshootAPIGatewayHTTPerrors analise o Amazon CloudWatch Logs, o runbook valida a API, o recurso, a operação e o estágio.

Conceda as permissões necessárias

Antes de executar o runbook, certifique-se de que seu usuário ou perfil do AWS Identity and Access Management (AWS IAM) tenha as permissões corretas. Verifique se seu perfil ou usuário do IAM tem permissão para acessar o runbook.

Além disso, o usuário do IAM ou o perfil de serviço assumido que executa a automação deve ter as seguintes permissões:

• apigateway:GET
• logs:GetQueryResults
• logs:StartQuery
• ssm:DescribeAutomationExecutions
• ssm:GetAutomationExecution
• ssm:DescribeAutomationStepExecutions
• ssm:StartAutomationExecution
• ssm:DescribeDocument
• ssm:GetDocument
• ssm:ListDocuments

Execute a automação

Conclua as seguintes etapas:

1. Abra o runbook AWSSupport-TroubleshootAPIGatewayHttpErrors.
2. Selecione Executar automação.
   Para parâmetros de entrada, insira o seguinte:
   RestApiId: O ID da API para a qual você está solucionando problemas.
   StageName: O nome do estágio implantado.
   ResourcePath: O caminho do recurso da operação.
   HttpMethod: o método para o caminho do recurso configurado.
   StartTime: A data e a hora de início para consultar os logs do CloudWatch. O formato deve ser yyyy-MM-ddTHH:mm:ss e o fuso horário deve ser o UTC.
   EndTime: A data e o horário de término para interromper a consulta dos logs do CloudWatch. O formato deve ser yyyy-MM-ddTHH:mm:ss e o fuso horário deve ser o UTC.
   Logs de acesso: Os logs de acesso que você deseja que o runbook analise.
   ID de execução: o ID de execução da solicitação que apresenta erros.
   AutomationAssumeRole: O ARN do perfil do IAM que permite que a Automação realize as ações em seu nome. Se você não especificar um perfil, a Automação usará as permissões do usuário que inicia o runbook.
   StageName: O nome do estágio implantado.
3. Selecione Executar.
4. Revise a seção Saídas para resultados detalhados.
   Observação: A automação é concluída com êxito, mesmo quando o runbook não encontra logs.

Solucionar manualmente os erros do código de status 5xx

Observação: A resolução a seguir se aplica somente às APIs REST.

Antes de começar, ative o Amazon CloudWatch Logs para solucionar erros do API Gateway. Para encontrar erros 5xx em seus logs de execução, consulte Como faço para encontrar erros do API Gateway API REST nos meus logs do CloudWatch? A métrica ](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-metrics-and-dimensions.html#api-gateway-metrics)5xxError[ do API Gateway captura o número de erros do lado do servidor em um período especificado.

Erros no código da função do Lambda

Para erros do terminal 500 da API que se integram ao AWS Lambda, consulte Padrões de tratamento de erros no Amazon API Gateway e no AWS Lambda.

Permissões ausentes para uma variável de estágio

Se você usar uma variável de estágio para configurar um API Gateway para invocar uma função do Lambda, você pode receber um erro interno do servidor. Para resolver este problema, consulte defini minha integração do Lambda no API Gateway usando uma variável de estágio. Por que recebo um “Internal server error” (Erro interno do servidor) e um código de status 500 quando invoco o método da API?

Mapeamento do código de status HTTP incorreto ou ausente

Para resolver esse problema, configure integrações simuladas no API Gateway.

Problemas de controle de utilização

Se um grande número de solicitações sobrecarregar o serviço backend, o API Gateway pode retornar um erro de servidor interno. Para resolver esse problema, ative um mecanismo de recuo exponencial e de nova tentativa e, em seguida, tente fazer a solicitação novamente. Se o problema persistir, verifique sua cota do API Gateway. Se você exceder a cota do serviço, é possível solicitar um aumento na cota do serviço.

Método HTTP indefinido do POST

Para a integração com o Lambda, você deve usar o método HTTP do POST para a solicitação de integração. Execute o seguinte comando put-integration da AWS CLI para atualizar a solicitação de integração do método:

aws apigateway put-integration \
    --rest-api-id id \
   --resource-id id \
    --http-method ANY \
    --type AWS_PROXY \
    --integration-http-method POST \
    --uri arn:aws:apigateway:us-east-2:lambda:path//2015-03-31/functions/arn:aws:lambda:us-east-2:account_id:function:helloworld/invocations

Observação: Substitua a rest-api-id pelo ID da sua API REST, resource-id pelo ID do seu recurso e o URI de exemplo pelo seu URI.

Em seguida, execute o seguinte comando create-deployment da AWS CLI para implantar a API REST:

aws apigateway create-deployment \
    --rest-api-id id \
    --stage-name stage-resource

Observação: Substitua rest-api-id pelo ID da sua API REST e stage-resource pelo seu recurso Estágio para criar o recurso Deployment.

Permissões do Lambda

Certifique-se de que a política baseada em recursos da sua função do Lambda ou do autorizador do Lambda inclui permissões para que sua API possa invocar a função.

Problema no formato JSON de saída da função do Lambda

Se a saída da sua função do Lambda integrada não estiver em conformidade com o formato JSON especificado para as APIs REST, você receberá um erro. Certifique-se de usar o formato JSON correto para a saída das funções do Lambda para integrações de proxy e dos autorizadores do Lambda. Use o exemplo de formatos JSON a seguir.

Exemplo de função do Lambda para integração de proxy:

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headerName": "headerValue", ... },
    "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
    "body": "..."
}

Exemplo de autorizador do Lambda:

{
   "principalId": "user",
  "policyDocument": {
    "Version": "2012-10-17",
    "Statement": [
      { "Action": "execute-api:Invoke",
        "Effect": "Deny",
        "Resource": "arn:aws:execute-api:us-west-2:123456789012:ymy8tbxw7b/dev/GET/"
      }
    ]
  }
}

Tamanho da carga útil de backend excede 10 MB

A cota máxima da API HTTP para um tamanho de carga útil de backend é de 10 MB. Não é possível aumentar o tamanho, então certifique-se de que o tamanho da carga útil do backend não exceda a cota de 10 MB.

Integração de terminais privados

Se você usar um endpoint de API privada, também deverá configurar a integração privada do API Gateway.

Falhas no serviço interno

Se a AWS tiver problemas internos de serviço, você poderá receber um erro 500. Aguarde até que o problema seja resolvido na AWS ou no serviço API Gateway e tente novamente a solicitação com um recuo exponencial.

Erro do código de status 502: Bad gateway

Você recebe um código de status 502 Bad Gateway quando o API Gateway não consegue processar a resposta como gateway ou proxy. Para solucionar esse problema, consulte Como resolvo erros 502 de HTTP das APIs REST do API Gateway com a integração do proxy Lambda?

Observação: Quando o API Gateway lê a resposta do serviço de backend, ele usa modelos de mapeamento para mapear o formato na seção de resposta de integração. Para obter mais informações, consulte Configurar uma resposta de integração no API Gateway.

Erro do código de status 503: Service unavailable

Um erro de código de status 503 ocorre porque a integração de backend não está disponível e, portanto, a API do API Gateway não recebe uma resposta.

Esse erro pode ocorrer pelos seguintes motivos:

• O servidor de backend excedeu a capacidade e não consegue processar novas solicitações de clientes.
• O servidor de backend está concluindo a manutenção temporária.

Para resolver esse problema, é possível adicionar mais recursos ao servidor de backend e ativar um mecanismo de recuo exponencial e repetição no cliente. Em seguida, tente a solicitação novamente.

Erro do código de status 504: Endpoint request timed out

Se uma solicitação de integração demorar mais do que o parâmetro máximo de tempo limite de integração da sua API Gateway API REST, o API Gateway retornará um código de status HTTP 504. Para resolver esse problema, consulte Como posso solucionar erros de tempo limite HTTP 504 com o API Gateway?

Informações relacionadas

Fluxos de trabalho de automação do AWS Support (SAW)

Práticas de segurança recomendadas no Amazon API Gateway

Monitoramento da execução da API REST com métricas do Amazon CloudWatch

Como faço para ativar o CloudWatch Logs para solucionar problemas com minha API REST do API Gateway ou API de WebSocket?