Como posso solucionar erros 5xx do API Gateway?

Data da última atualização: 22/09/2021

Quando chamo minha API do Amazon API Gateway, recebo um erro 5xx. Como soluciono problemas de erros 5xx do API Gateway?

Breve descrição

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

  • 500 servidor interno
  • 502 gateway incorreto
  • 503 serviço indisponível
  • 504 tempo limite da solicitação do endpoint

Resolução

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

Você pode usar o Amazon CloudWatch Logs para encontrar erros 5xx no API Gateway. A métrica 5xxError do API Gateway conta o número de erros do lado do servidor capturados em um determinado período.

Observação: se 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 ter as seguintes causas:

  • Erros no código da função do AWS Lambda.
  • Permissões ausentes para usar uma variável de estágio.
  • Mapeamento incorreto ou ausente do código de status HTTP.
  • Problemas de limitação.
  • O método HTTP de POST não está definido.
  • Permissões do Lambda.
  • Problema no formato JSON da função Lambda.
  • O tamanho da carga útil do backend ultrapassou 10 MB.
  • Integração de endpoints privados.

Erros no código da função Lambda

Os erros 500 de endpoints de 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ê configurou um API Gateway para invocar uma função do AWS Lambda usando uma variável de estágio, poderá receber um “erro interno do servidor”. Para resolver esse erro, consulte Por que recebo um “Erro interno do servidor” e um código de status 500 quando invoco o método da API?

Mapeamento incorreto ou ausente do código de status HTTP

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

Problemas de limitação

Se o serviço de backend for limitado devido a um grande número de solicitações, a API do API Gateway pode retornar um “Erro interno do servidor”. Você pode ativar um mecanismo de recuo exponencial e repetição e tentar a solicitação novamente. Se o problema persistir, verifique o limite de cota do API Gateway. Se você excedeu o limite de cota de serviço, poderá solicitar um aumento de cota.

O método HTTP de POST não está definido

Para integração com o Lambda, você deve usar o método HTTP de POST para a solicitação de integração.

Atualize a solicitação de integração do método usando o comando put-integration da AWS CLI semelhante ao seguinte:

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, implante a API REST usando o comando create-deployment da AWS CLI, semelhante ao seguinte:

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

Permissões do Lambda

Certifique-se de que a função integrada do Lambda ou a política baseada em recursos dos autorizadores do Lambda inclua permissões para a sua API invocar a função. Siga as instruções para atualizar a política baseada em recursos da sua função do Lambda.

Problema no 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 a função autorizadora do Lambda no formato JASON, semelhante ao seguinte:

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": "..."
}

O tamanho da carga útil do backend excedeu 10 MB

O tamanho máximo da carga útil do backend é de 10 MB e não pode ser aumentado. Certifique-se de que o tamanho da carga útil do backend não exceda a cota padrão de 10 MB.

Integração de endpoints privados

Se você estiver usando um endpoint de API privado, também deverá configurar a integração privada com o API Gateway. Siga as instruções para configurar integrações privadas do API Gateway.

Erro 502: gateway incorreto

Um código de erro 502 está relacionado ao serviço da AWS ao qual o API Gateway se integra, como uma função do AWS Lambda. O API Gateway não conseguiu processar a resposta como um gateway ou proxy.

Para solucionar problemas de erro 502 quando integrado a uma função de proxy do Lambda, consulte Como resolvo erros HTTP 502 de APIs REST do API Gateway com integração de proxy Lambda?

Observação: o API Gateway interpreta a resposta do serviço de back-end em um formato que pode ser mapeado na seção de resposta de integração usando modelos de mapeamento. 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 de back-end, e a API do API Gateway não consegue receber uma resposta.

Esse erro pode ocorrer se o servidor de back-end:

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

Para resolver esse erro, considere o provisionamento de mais recursos para o servidor de back-end e a ativação de um mecanismo de recuo exponencial e repetição no cliente. Em seguida, tente fazer a solicitação novamente.

Erro 504: tempo limite da solicitação do endpoint

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 HTTP 504.

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