Knowledge Center Monthly Newsletter - June 2025
Stay up to date with the latest from the Knowledge Center. See all new Knowledge Center articles published in the last month, and re:Post's top contributors.
Como posso solucionar erros de invocação HTTP do API Gateway?
Quero solucionar erros de invocação do Amazon 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:
- Abra o runbook AWSSupport-TroubleshootAPIGatewayHttpErrors.
- 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. - Selecione Executar.
- 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

Conteúdo relevante
- feita há um mês
- feita há 3 meses
- feita há 3 meses
- AWS OFICIALAtualizada há 4 anos