Comment puis-je résoudre les erreurs 5xx pour la Passerelle API ?

Brève description

Les codes de réponse HTTP 5xx indiquent des erreurs de serveur. Les erreurs de Passerelle API 5xx incluent les cas suivants :

• Serveur interne 500
• 502 mauvaise passerelle
• Service 503 non disponible
• Le délai de la requête 504 sur le terminal a expiré

Résolution

Avant de commencer, suivez les étapes pour activer Amazon CloudWatch Logs afin de résoudre les erreurs de la Passerelle API.

Utilisez les journaux CloudWatch pour détecter les erreurs 5xx provenant de la Passerelle API. La métrique 5XXError de la Passerelle API compte le nombre d'erreurs côté serveur capturées au cours d'une période donnée.

**Remarque :**Si vous recevez des erreurs lors de l'exécution des commandes de l'interface de la ligne de commande AWS (AWS CLI), assurez-vous que vous utilisez la version la plus récente de l’AWS CLI.

Erreur 500 : erreur interne du serveur

Cette erreur peut se produire en raison de l'un des scénarios suivants :

• Erreurs dans le code de la fonction AWS Lambda
• Autorisations manquantes pour l'utilisation d'une variable d'étape
• Mappage du code d'état HTTP incorrect ou manquant
• Problèmes de limitation
• Méthode HTTP non définie de POST
• Autorisations Lambda
• Problème de format JSON de la fonction Lambda
• Taille de la charge utile du backend supérieure à 10 Mo
• Intégration de terminaux privés
• Défaillances de service internes

Erreurs dans le code de la fonction Lambda

Les erreurs du point de terminaison 500 de l'API qui s'intègrent à Lambda peuvent indiquer que le code de la fonction Lambda contient une erreur. Pour plus d'informations et pour résoudre les problèmes, consultez Modèles de gestion des erreurs dans Amazon API Gateway et AWS Lambda.

Autorisations manquantes pour l'utilisation d'une variable d'étape

Si vous utilisez une variable d'étape pour configurer une passerelle API afin d'appeler une fonction Lambda, vous pouvez recevoir une erreur de serveur interne. Pour résoudre cette erreur, voir J'ai défini mon intégration Lambda dans la Passerelle API à l'aide d'une variable d'étape. Pourquoi est-ce que je reçois une « Erreur interne du serveur » et un code d'état 500 lorsque j'appelle la méthode API ?

Mappage du code d'état HTTP incorrect ou manquant

Un mappage de code d'état HTTP incorrect ou manquant peut également entraîner 500 erreurs. Pour résoudre ce problème, configurez des intégrations fictives dans la Passerelle API.

Problèmes de limitation

Si un nombre élevé de demandes limite le service principal, l'API de la Passerelle API peut renvoyer une erreur de serveur interne. Pour résoudre ce problème, activez un mécanisme d’interruption exponentielle et réessayez, puis réessayez d'exécuter la demande. Si le problème persiste, vérifiez la limite de quota de votre Passerelle API. Si vous dépassez la limite de quota de service, vous pouvez demander une augmentation de quota.

Méthode HTTP non définie de POST

Pour l'intégration Lambda, vous devez utiliser la méthode HTTP POST pour la demande d'intégration.

Exécutez la commande put-integration de l’AWS CLI pour mettre à jour la demande d'intégration des méthodes :

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

Utilisez ensuite la commande create-deployment de l’AWS CLI pour déployer l'API REST :

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

Autorisations Lambda

Assurez-vous que la politique basée sur les ressources de la fonction Lambda intégrée ou de l'autorisateur Lambda inclut des autorisations permettant à votre API d'invoquer la fonction. Suivez les instructions pour mettre à jour la politique basée sur les ressources de votre fonction Lambda.

Problème de format JSON de la fonction Lambda

La fonction Lambda intégrée ne renvoie pas de sortie conformément au format JSON prédéfini pour les API REST et les API HTTP. Mettez à jour votre fonction Lambda ou votre autorisateur Lambda au format 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": "..."
}

Taille de la charge utile du backend supérieure à 10 Mo

La taille maximale de la charge utile du backend est de 10 Mo. Vous ne pouvez pas augmenter la taille. Assurez-vous que la taille de la charge utile du backend ne dépasse pas le quota par défaut de 10 Mo.

Intégration de terminaux privés

Si vous utilisez un point de terminaison d'API privé, vous devez également configurer l'intégration privée de la Passerelle API. Suivez les instructions pour configurer les intégrations privées de la Passerelle API.

Défaillances de service internes

Si AWS rencontre des problèmes de service internes, il est possible que vous receviez un message d'erreur 500. Attendez que le problème soit résolu au sein d'AWS ou du service de Passerelle API, puis réessayez d'exécuter la demande en répétant de manière exponentielle.

Erreur 502 : passerelle incorrecte

Un code d'erreur 502 est lié au service AWS auquel votre Passerelle API s'intègre, tel qu'une fonction AWS Lambda. La Passerelle API ne peut pas traiter la réponse en tant que passerelle ou proxy.

Pour résoudre ce problème, consultez l'article Comment résoudre les erreurs HTTP 502 provenant des API REST de la Passerelle API avec intégration de proxy Lambda ?

**Remarque :**Lorsque la Passerelle API interprète la réponse du service principal, elle utilise des modèles de mappage pour mapper le format dans la section de réponse d'intégration. Pour plus d'informations, consultez la section Configurer une réponse d'intégration dans la Passerelle API.

Erreur 503 : service non disponible

Un code d'erreur 503 est lié à l'intégration du backend et si l'API de la Passerelle API ne parvient pas à recevoir de réponse.

Cette erreur peut se produire dans les scénarios suivants :

• Le serveur principal est surchargé et ne peut pas traiter les nouvelles demandes des clients.
• Le serveur principal fait l'objet d'une maintenance temporaire.

Pour résoudre cette erreur, envisagez de fournir davantage de ressources au serveur principal et d'activer un mécanisme d'interruption exponentielle et de nouvelles tentatives sur le client. Réessayez ensuite d'effectuer la demande.

Erreur 504 : délai de la demande de point de terminaison dépassé

Si une demande d'intégration prend plus de temps que le paramètre de délai d'intégration maximal de votre API REST de la Passerelle API, la Passerelle API renvoie un code d'état HTTP 504.

Pour résoudre cette erreur, consultez l'article Comment puis-je résoudre les erreurs de délai d'expiration de l'API HTTP 504 avec la Passerelle API ?

Informations connexes

Bonnes pratiques de sécurité dans Amazon API Gateway

Surveillance de l'exécution de l'API REST avec les métriques Amazon CloudWatch