Como soluciono erros 500 ao usar integrações de link de VPC com APIs REST do API Gateway?

Breve descrição

As integrações do API Gateway com links de VPC podem falhar ao encaminhar o tráfego para recursos de backend.

Elas também podem retornar um código de status "HTTP 500" por um dos seguintes motivos:

• O link de VPC está no estado Falha. Ou o serviço de endpoint não existe ou está no estado Rejeitado.
• O grupo de destino mostra o destino registrado como não íntegro ou não em uso.
• Grupos de segurança não permitem tráfego em portas específicas.
• A lista de controle de acesso à rede (ACL da rede) bloqueia o tráfego.
• O destino não recebe nas portas de destino.
• O certificado do nome de domínio não corresponde ao Network Load Balancer ou ao Application Load Balancer ativado por TLS.

Se você ativou o Amazon CloudWatch Logs para sua API, uma mensagem de erro com a causa do erro aparecerá nos logs de execução.

Resolução

Valide a conectividade de backend

Antes de solucionar problemas do API Gateway, execute uma das seguintes ações:

• Use ferramentas, como curl ou Postman, para enviar uma solicitação para o nome DNS do Network Load Balancer de dentro da sua VPC. Se a solicitação falhar, então há um problema com a configuração do Network Load Balancer, a integridade do destino de backend ou a rede.
• Use o VPC Reachability Analyzer para validar o fluxo de tráfego das sub-redes de links de VPC do API Gateway para seus recursos de backend.

Confirme a causa do erro

Ative o registro em log da API do CloudWatch. Além disso, configure o registro em log de execução.

Observação: ao definir as configurações de registro em log, defina o nível de registro em log como Logs de erro e informações e selecione Rastreamento de dados. Essas configurações fornecem os logs completos de solicitação e resposta.

Para identificar a causa dos erros, examine os logs de execução das APIs REST no CloudWatch. Em seguida, solucione o problema com base na mensagem de erro recebida.

Solucionar erro "There was an internal error while executing your request"

Você recebe a seguinte mensagem de erro:

"Error: Execution failed due to configuration error: There was an internal error while executing your request"

Para resolver esse problema, verifique as seguintes configurações:

• O balanceador de carga do link de VPC existe e não foi excluído.
• O link de VPC está no estado Disponível. Se o link de VPC estiver no estado Falha, você deve criar um novo link de VPC e associá-lo à sua API.
  Observação: implante a API depois de modificar a solicitação de integração.
• A conexão de endpoint do link de VPC associada ao seu Network Load Balancer de destino está no estado Disponível.
• Você listou o ID da conta do API Gateway específico da região da AWS em Permitir entidades principais.
• Uma conexão de endpoint da conta do API Gateway nas Conexões de endpoint do serviço de endpoint está no estado Disponível.
• Se o API Gateway referenciar o ID da VPC com uma variável de estágio, verifique se o ID do link de VPC está correto.
• O balanceador de carga do link de VPC recebe na porta HTTP/HTTPS para a qual você configurou a solicitação. Certifique-se de que você configurou os receptores para a porta correta e se as ACLs da rede não bloqueiam a solicitação.
• O grupo de destino aceita a solicitação. As ACLs da rede devem permitir tráfego de entrada e saída e os grupos de segurança devem permitir tráfego de entrada para as portas configuradas.
• Se a solicitação retornar um erro de código de status "HTTP 500", a conexão pode receber o número total de pacotes de reinicialização (RST) do TCP. O servidor de backend deve estar em execução. Além disso, um serviço deve estar em execução no destino de backend da porta de destino. Verifique se o destino de backend recebe na porta de destino.
• Você desativou as regras de entrada para o tráfego do AWS PrivateLink. A opção Aplicar regras de entrada no tráfego do PrivateLink aplica todas as regras do grupo de segurança de entrada e saída ao tráfego do link de VPC. Se você não configurar o grupo de segurança para permitir tráfego do link de VPC, ele poderá bloquear o tráfego do API Gateway.

Solucionar erro "Host name 'domain.com.com' does not match the certificate subject provided by the peer"

Você recebe a seguinte mensagem de erro:

"Error: Execution failed due to configuration error: Host name 'domain.com.com' does not match the certificate subject provided by the peer (CN=myinstance.com)"

Certifique-se de que o nome de domínio do endpoint corresponde ao certificado que o destino do balanceador de carga ativado por TLS retorna. Os certificados que você configura na instância de destino devem ser confiáveis na lista de provedores de autoridade de certificação compatíveis.

Solucionar erro "PKIX path building failed:...unable to find valid certification path to requested target"

Você recebe a seguinte mensagem de erro:

"Error: Execution failed due to configuration error: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target"

Esse erro ocorre quando o serviço da API REST sinaliza um certificado que a integração retorna como inválido. Mesmo quando insecureSkipVerification é definido como true na propriedade TlsConfig da integração, o API Gateway executa a validação básica do certificado.

O API Gateway analisa as seguintes informações:

• A data de validade do certificado
• O nome do host
• A presença de uma autoridade de certificação (CA) raiz
  Observação: a integração deve incluir e retornar a cadeia de certificado completa para que o API Gateway verifique a cadeia de confiança e estabeleça uma conexão segura. A cadeia completa inclui todos os certificados intermediários, desde o certificado do servidor até o certificado CA raiz. Além disso, a CA raiz deve incluir keyUsage com keyCertSign e basicConstraints com CA:TRUE. Para obter mais informações, consulte x-amazon-apigateway-integration.tlsConfig object.

Solucionar erro "Cannot verify ECDH ServerKeyExchange signature"

Você recebe a seguinte mensagem de erro:

"Error: Execution failed due to configuration error: Cannot verify ECDH ServerKeyExchange signature"

Esse erro ocorre quando uma chave e o certificado correspondente não coincidem e o handshake TLS falha. Para resolver esse problema, verifique o conteúdo dos arquivos que você usou para suas CAs, chaves e certificados configurados.

Solucionar erro "Execution failed due to an internal error"

Você recebe a seguinte mensagem de erro:

"Error: Execution failed due to an internal error"

Esse erro ocorre quando o API Gateway não se conecta ao balanceador de carga pelo link de VPC porque o destino é redefinido no balanceador de carga. Para resolver esse problema, defina um tempo limite maior no destino do que o tempo limite padrão de 350 segundos do balanceador de carga.

Solucionar erro "Execution failed due to a VPC link error"

Você recebe a seguinte mensagem de erro:

"Error: Execution failed due to a VPC link error"

O API Gateway tem muitas dependências. É possível ver erros quando uma das dependências tem falhas de conexão transitórias. Para erros de baixa frequência, é uma prática recomendada implementar novas tentativas com recuo exponencial. Se a frequência de erros for alta, entre em contato com o AWS Support. Certifique-se de fornecer os logs de execução do API Gateway que apresentam os erros.

Solucionar erro "Execution failed due to configuration error: Not a valid protocol version"

Você recebe a seguinte mensagem de erro:

"Error: Execution failed due to configuration error: Not a valid protocol version"

Esse erro ocorre quando a integração responde com uma resposta HTTP que não é válida e não está de acordo com a especificação HTTP. O backend integrado pode enviar de volta dados que não são válidos para o API Gateway.

Para solucionar esse problema, realize as seguintes ações:

• Reproduza a solicitação feita a partir do API Gateway. Para testar o endpoint de serviço que o API Gateway usa, crie um endpoint da VPC que esteja vinculado ao ID do endpoint de serviço. Também é possível executar capturas de pacotes para analisar a resposta retornada do backend integrado.
• Para evitar criptografia duplicada, altere o protocolo do balanceador de carga para TLS ou TCP, dependendo da resposta dos destinos.
• Certifique-se de que insecureSkipVerification esteja definido como true na propriedade TlsConfig da integração.

Monitore e detecte erros e problemas

Use as ferramentas a seguir para identificar se o problema é transitório ou se há problemas persistentes de configuração:

• Monitore as métricas 5XXError e IntegrationLatency do API Gateway no CloudWatch para detectar padrões.
• Ative o rastreamento AWS X-Ray para monitorar caminhos de solicitação do API Gateway para o link de VPC, do link de VPC para o Network Load Balancer e do Network Load Balancer para o backend.

Informações relacionadas

Understanding VPC links in Amazon API Gateway private integrations (Entendendo links de VPC nas integrações privadas do Amazon API Gateway)

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

Configurar um Network Load Balancer para integrações privadas do API Gateway (legado)