Comment résoudre 500 erreurs lorsque j'utilise des intégrations de liens VPC avec les API REST API Gateway ?

Brève description

API Gateway avec intégrations de liens VPC peut ne pas transférer le trafic vers les ressources backend.

Il peut également renvoyer un code d'état « HTTP 500 » pour l'une des raisons suivantes :

• Le lien VPC se trouve à l'état Échec. Ou le service de point de terminaison n'existe pas ou se trouve à l’état Rejeté.
• Le groupe cible indique que la cible enregistrée n'est pas saine ou n'est pas utilisée.
• Les groupes de sécurité n'autorisent pas le trafic sur des ports spécifiques.
• La liste de contrôle d'accès au réseau (ACL réseau) bloque le trafic.
• La cible n'écoute pas sur les ports cibles.
• Le certificat de nom de domaine ne correspond pas au Network Load Balancer ou à l'Application Load Balancer activé par TLS.

Si vous avez activé Amazon CloudWatch Logs pour votre API, un message d'erreur indiquant la cause de l'erreur apparaît dans les journaux d'exécution.

Résolution

Valider la connectivité du backend

Avant de résoudre les problèmes liés à API Gateway, effectuez l'une des actions suivantes :

• Utilisez des outils tels que curl ou Postman pour envoyer une requête au nom DNS du Network Load Balancer depuis votre VPC. Si la requête échoue, il existe un problème au niveau de la configuration de votre Network Load Balancer, de l'état de la cible du backend ou de la mise en réseau.
• Utilisez l’Analyseur d'accessibilité du VPC pour valider le flux de trafic depuis les sous-réseaux de liens VPC d'API Gateway vers vos ressources backend.

Confirmer l’origine de l’erreur

Activez la journalisation de l'API CloudWatch. Configurez également la journalisation des exécutions.

Remarque : Lorsque vous configurez les paramètres de journalisation, définissez le niveau de journalisation sur Journaux d'erreurs et d'informations et sélectionnez Suivi des données. Ces paramètres vous fournissent les journaux complets des requêtes et des réponses.

Pour identifier la cause des erreurs, consultez les journaux d'exécution des API REST dans CloudWatch. Puis, remédiez au problème en fonction du message d'erreur reçu.

Résoudre l’erreur « There was an internal error while executing your request »

Le message d’erreur suivant s’affiche :

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

Pour résoudre ce problème, vérifiez les configurations suivantes :

• L’équilibreur de charge des liens VPC existe et il n'a pas été supprimé.
• Vérifiez que le lien VPC se trouve à l'état Disponible. Si le lien VPC se trouve à l'état Échec, vous devez créer un nouveau lien VPC et l'associer à votre API.
  Remarque : Déployez l'API après avoir modifié la demande d'intégration.
• La connexion de point de terminaison du lien VPC associée à votre Network Load Balancer cible se trouve à l'état Disponible.
• Vous avez répertorié l'ID de compte API Gateway spécifique à la région AWS dans Autoriser les principaux.
• Une connexion de point de terminaison depuis le compte API Gateway dans les connexions de point de terminaison du service de point de terminaison se trouve à l'état Disponible.
• Si API Gateway fait référence à l’ID du VPC avec une variable d'étape, vérifiez que l'ID de lien VPC est correct.
• L'équilibreur de charge des liens VPC écoute le port HTTP/HTTPS pour lequel vous avez configuré la requête. Assurez-vous que vous avez configuré les écouteurs pour le port correct et que les ACL réseau ne bloquent pas la requête.
• Vérifiez que le groupe cible accepte la requête. Les ACL réseau doivent autoriser le trafic entrant et sortant, et les groupes de sécurité doivent autoriser le trafic entrant pour les ports configurés.
• Si la requête renvoie une erreur de code d'état « HTTP 500 », la connexion peut recevoir le nombre total de paquets de réinitialisation (RST) TCP. Le serveur de backend doit être en cours d'exécution. En outre, un service doit être exécuté sur la cible backend du port cible. Vérifiez que la cible backend écoute sur le port cible.
• Vous avez désactivé les règles entrantes pour le trafic AWS PrivateLink. L'option Appliquer les règles entrantes au trafic PrivateLink applique toutes les règles entrantes et sortantes du groupe de sécurité au trafic provenant du lien VPC. Si vous ne configurez pas le groupe de sécurité pour autoriser le trafic provenant du lien VPC, le groupe de sécurité pourrait bloquer le trafic API Gateway.

Résoudre le message d’erreur « Host name 'domain.com.com' does not match the certificate subject provided by the peer »

Le message d’erreur suivant s’affiche :

« 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) »

Assurez-vous que le nom de domaine du point de terminaison correspond au certificat renvoyé par la cible de l'équilibreur de charge activé par TLS. La liste des fournisseurs d'autorité de certification pris en charge doit approuver les certificats que vous configurez au niveau de l’instance cible.

Résoudre le message « PKIX path building failed:...unable to find valid certification path to requested target »

Le message d’erreur suivant s’affiche :

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

Cette erreur se produit lorsque le service d'API REST signale un certificat renvoyé par l'intégration comme étant non valide. Même lorsque vous avez défini l'option insecureSkipVerification sur vrai dans la propriété TlsConfig de l’intégration, API Gateway effectue la validation de base du certificat.

API Gateway examine les informations suivantes :

• La date d'expiration du certificat
• Le nom d'hôte
• La présence d'une autorité de certification racine (CA)
  Remarque : L'intégration doit inclure et renvoyer la chaîne de certificats complète pour API Gateway afin de vérifier la chaîne d’approbation et d'établir une connexion sécurisée. La chaîne complète inclut tous les certificats intermédiaires, du certificat du serveur au certificat CA racine. En outre, l'autorité de certification racine doit inclure keyUsage avec keyCertSign et basicConstraints avec CA:TRUE. Pour plus d'informations, consultez l'objet x-amazon-apigateway-integration.tlsConfig.

Résoudre le message « Cannot verify ECDH ServerKeyExchange signature »

Le message d’erreur suivant s’affiche :

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

Cette erreur se produit lorsqu'une clé et le certificat associé ne correspondent pas et que TLS Handshake échoue. Pour résoudre ce problème, vérifiez le contenu des fichiers que vous avez utilisés pour les CA, les certificats et les clés que vous avez configurés.

Résoudre le message « Execution failed due to an internal error »

Le message d’erreur suivant s’affiche :

« Error: Execution failed due to an internal error »

Cette erreur se produit quand API Gateway ne s'est pas connecté à l'équilibreur de charge via le lien VPC en raison de la réinitialisation de la cible sur l'équilibreur de charge. Pour résoudre ce problème, définissez sur la cible un délai d'expiration plus long que le délai d'expiration par défaut (350 secondes) défini sur l'équilibreur de charge.

Résoudre le message « Execution failed due to a VPC link error »

Le message d’erreur suivant s’affiche :

« Error: Execution failed due to a VPC link error »

API Gateway comprend de nombreuses dépendances. Des erreurs peuvent s'afficher lorsque l'une des dépendances présente des échecs de connexion transitoires. Pour les erreurs de basse fréquence, il est recommandé d'implémenter de nouvelles tentatives avec un backoff exponentiel. Si la fréquence des erreurs est élevée, contactez AWS Support. Assurez-vous de fournir les journaux d'exécution d'API Gateway qui indiquent les erreurs.

Résoudre le message « Execution failed due to configuration error: Not a valid protocol version »

Le message d’erreur suivant s’affiche :

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

Cette erreur se produit lorsque l'intégration répond par une réponse HTTP non valide et non conforme à la spécification HTTP. Le backend intégré peut renvoyer des données non valides à API Gateway.

Pour résoudre ce problème, procédez comme suit :

• Reproduisez la requête que vous avez effectuée depuis API Gateway. Pour tester le point de terminaison de service utilisé par API Gateway, créez le point de terminaison d'un VPC lié à l'ID du point de terminaison du service. Vous pouvez également exécuter des captures de paquets pour examiner la réponse renvoyée par le backend intégré.
• Pour éviter le double chiffrement, remplacez le protocole de l'équilibreur de charge par TLS ou TCP, en fonction de la réponse de la cible.
• Veillez à ce que l'option insecureSkipVerification soit définie sur vrai dans la propriété TlsConfig de l’intégration

Surveiller et détecter les erreurs et les problèmes

Utilisez les outils suivants pour déterminer si le problème est temporaire ou s'il existe des problèmes de configuration persistants :

• Surveillez les métriques API Gateway 5XXError et IntegrationLatency dans CloudWatch pour détecter des modèles.
• Activez le suivi AWS X-Ray pour surveiller les chemins des requêtes depuis API Gateway vers le lien VPC, le lien VPC vers le Network Load Balancer et le Network Load Balancer vers le backend.

Informations connexes

Comprendre les liens VPC dans les intégrations Amazon API Gateway privées

Surveiller l’exécution de l’API REST à l’aide des métriques Amazon CloudWatch

Configurer un Network Load Balancer pour les intégrations API Gateway privées