Como posso solucionar os erros 5xx do API Gateway?

Breve descrição

Os códigos de resposta HTTP 5xx indicam erros no servidor. Os erros 5xx do API Gateway incluem os seguintes casos:

• 500 servidor interno
• 502 gateway inválido
• 503 serviço indisponível
• 504 tempo limite da solicitação de endpoint atingido

Resolução

Antes de começar, siga as etapas para ativar o Amazon CloudWatch Logs para solucionar erros do API Gateway.

Use os logs do CloudWatch para encontrar erros 5xx do API Gateway. A métrica 5xxError do API Gateway conta o número de erros do lado do servidor que são capturados em um determinado período.

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

Erro 500: erro interno do servidor

Esse erro pode ocorrer devido a qualquer um dos seguintes cenários:

• Erros no código da função do AWS Lambda
• Permissões ausentes para usar uma variável de estágio
• Mapeamento do código de status HTTP incorreto ou ausente
• Problemas de limitação
• Método HTTP indefinido do POST
• Permissões do Lambda
• Problema de formato JSON da função do Lambda
• Tamanho da carga útil de back-end superior a 10 MB
• Integração de terminais privados
• Falhas no serviço interno

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

Os erros 500 do endpoint da API que se integram ao Lambda podem indicar que a função do Lambda tem um erro no código. Para obter mais informações e solução de problemas, consulte Padrões de tratamento de erros no Amazon API Gateway e no AWS Lambda.

Permissões ausentes para usar 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, poderá receber um erro interno do servidor. Para resolver esse erro, consulte Eu defini minha integração do Lambda no API Gateway usando uma variável de estágio. Por que recebo um “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

O mapeamento incorreto ou ausente do código de status HTTP também pode resultar em erros 500. Para resolver esse problema, configure integrações simuladas no API Gateway.

Problemas de limitação

Se um grande número de solicitações estiver limitando o serviço de back-end, a API do API Gateway poderá retornar um erro interno do servidor. 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 seu limite de cota do API Gateway. Se você exceder o limite da cota de serviço, poderá solicitar um aumento da cota.

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 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

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

aws apigateway create-deployment \
    --rest-api-id id \
    --stage-name <value>

Permissões do Lambda

Verifique se a política baseada em recursos da função integrada do Lambda ou do autorizador do Lambda inclui permissões para que sua API invoque a função. Siga as instruções para atualizar a política baseada em recursos da sua função do Lambda.

Problema de formato JSON da função do Lambda

A função do Lambda integrada não está retornando a saída de acordo com o formato JSON predefinido para APIs REST e APIs HTTP. Atualize sua função do Lambda ou o autorizador do Lambda no formato JSON:

API REST:

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

API HTTP:

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headername": "headervalue", ... },
    "multiValueHeaders": { "headername": ["headervalue", "headervalue2", ...], ... },
    "body": "..."
}

Tamanho da carga útil de back-end superior a 10 MB

O tamanho máximo da carga útil do back-end é de 10 MB. Você não pode aumentar o tamanho. Verifique se o tamanho da carga útil do back-end não exceda a cota padrão de 10 MB.

Integração de terminais privados

Se você estiver usando um endpoint de API privado, também deverá configurar a integração privada do API Gateway. Siga as instruções para configurar as integrações privadas 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 502: gateway incorreto

Um código de erro 502 está relacionado ao serviço da AWS ao qual seu API Gateway se integra, como uma função do AWS Lambda. O API Gateway não pode 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 interpreta a resposta do serviço de back-end, 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 503: serviço indisponível

Um código de erro 503 está relacionado à integração do back-end e se a API do API Gateway não pode receber uma resposta.

Esse erro pode ocorrer nos seguintes cenários:

• O servidor de back-end está sobrecarregado além da capacidade e não consegue processar novas solicitações de clientes.
• O servidor de back-end está em manutenção temporária.

Para resolver esse erro, considere provisionar mais recursos para o servidor de back-end e ativar um mecanismo exponencial de recuo e de nova tentativa no cliente. Em seguida, tente a solicitação novamente.

Erro 504: tempo limite da solicitação de endpoint atingido

Se uma solicitação de integração demorar mais do que o parâmetro de tempo limite máximo de integração da API REST do API Gateway, o API Gateway retornará um código de status 504 de HTTP.

Para resolver esse erro, consulte Como posso solucionar erros de tempo limite 504 da API HTTP com o API Gateway?

Informações relacionadas

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

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