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

Dernière mise à jour : 22/09/2022

Lorsque j'appelle mon API Amazon API Gateway, je reçois une erreur 5xx. Comment résoudre les erreurs 5xx de l'API Gateway ?

Brève description

Les codes de réponse HTTP 5xx indiquent des erreurs de serveur. Les erreurs 5xx de l'API Gateway incluent :

  • 500, serveurs internes
  • 502, mauvaise passerelle
  • 503, service non disponible
  • 504, délai d'attente dépassé pour la demande de point de terminaison

Solution

Avant de commencer, suivez les étapes pour activer Amazon CloudWatch Logs afin de résoudre les erreurs d'API Gateway.

Vous pouvez utiliser Amazon CloudWatch Logs pour rechercher les erreurs 5xx provenant d'API Gateway. La métrique 5XXError d'API Gateway 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 de commandes de l'Interface de la ligne de commande AWS (AWS CLI), assurez-vous d'utiliser la version la plus récente de l'AWS CLI.

Erreur 500 : erreur de serveur interne

Cette erreur peut être due à :

  • Erreurs dans le code de la fonction AWS Lambda.
  • Autorisations manquantes pour l'utilisation d'une variable d'étape.
  • Mappage de code d'état HTTP incorrect ou manquant.
  • Problèmes de limitation.
  • La méthode HTTP de POST n'est pas définie.
  • Autorisations Lambda.
  • Problème de format JSON de la fonction Lambda.
  • La taille de la charge utile du backend a dépassé 10 Mo.
  • Intégration d'un point de terminaison privé.

Erreurs dans le code de la fonction Lambda

Les erreurs 500 des points de terminaison d'API qui s'intègrent à Lambda peuvent indiquer que la fonction Lambda contient une erreur dans le code. Pour plus d'informations et pour résoudre les problèmes, consultez Schémas de traitement des erreurs dans Amazon API Gateway et AWS Lambda (Français non garanti).

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

Si vous configurez une API Gateway pour appeler une fonction AWS Lambda à l'aide d'une variable d'étape, vous risquez de recevoir une « erreur de serveur interne ». Pour résoudre cette erreur; consultez Je reçois une « erreur de serveur interne » et un code d'état 500 lorsque j'appelle la méthode d'API. Pourquoi ?

Mappage de code d'état HTTP incorrect ou manquant

Un mappage de code d'état HTTP incorrect ou manquant peut également entraîner des erreurs 500. Pour résoudre cette erreur, vous pouvez configurer des intégrations fictives dans API Gateway.

Problèmes de limitation

Si le service backend est limité en raison d'un nombre élevé de demandes, l'API API Gateway peut renvoyer une « erreur de serveur interne ». Vous pouvez activer unmécanisme de backoff exponentiel et de relance et réessayer la demande. Si le problème persiste, vérifiez votrelimite de quota API Gateway. Si vous avez dépassé la limite de quota de service, vous pouvez demander une augmentation du quota.

La méthode HTTP de POST n'est pas définie

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

Mettez à jour la demande d'intégration de méthode à l'aide de la commande AWS CLI put-integration similaire à ce qui suit :

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

Déployez ensuite l'API REST à l'aide de la commande AWS CLI create-deployment similaire à ce qui suit :

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

Autorisations Lambda

Assurez-vous que la fonction Lambda intégrée ou la politique basée sur les ressources des autorisateurs Lambda inclut des autorisations pour que votre API puisse appeler 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 la sortie selon le format JSON prédéfini pour les API REST et les API HTTP. Mettez à jour le format JASON de votre fonction Lambda ou de votre fonction d'autorisateur Lambda de manière similaire à ce qui suit :

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

La taille de la charge utile du backend a dépassé 10 Mo

La taille maximale de la charge utile du backend est de 10 Mo et ne peut pas être augmentée. 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 d'un point de terminaison privé

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

Erreur 502 : mauvaise passerelle

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

Pour résoudre l'erreur 502 lorsqu'elle est intégrée à une fonction proxy Lambda, voir Comment résoudre les erreurs HTTP 502 à partir des API REST API Gateway avec intégration de proxy Lambda ?

Remarque : API Gateway interprète la réponse du service d'arrière-plan dans un format qui peut être mappé dans la section de réponse d'intégration à l'aide de modèles de mappage. Pour plus d'informations, consultez Configuration d'une réponse d'intégration dans API Gateway.

Erreur 503 : service non disponible

Un code d'erreur 503 est lié à l'intégration d'arrière-plan et l'API de API Gateway ne peut pas recevoir de réponse.

Cette erreur peut se produire si le serveur d'arrière-plan est :

  • Surchargé au-delà de la capacité et ne peut pas traiter les nouvelles demandes des clients.
  • Le serveur d'arrière-plan est en maintenance temporaire.

Pour résoudre cette erreur, envisagez de provisionner davantage de ressources sur le serveur d'arrière-plan et d'activer un mécanisme de backoff exponentiel et de relance sur le client. Ensuite, réessayez la demande.

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

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

Pour résoudre cette erreur, consultez Comment résoudre les erreurs de délai d’expiration API HTTP 504 sur la passerelle API ?