Comment résoudre les erreurs d'appel HTTP d'API Gateway ?

Résolution

Pour résoudre les erreurs 5xx pour les API REST que vous avez configurées pour journaliser les demandes de ressources et d'opérations, utilisez le dossier d’exploitation AWSSupport-TroubleshootAPIGatewayHttpErrors.

Vous pouvez également résoudre manuellement les erreurs 5xx.

Remarque : Si des erreurs surviennent lorsque vous exécutez des commandes de l'interface de la ligne de commande AWS (AWS CLI), consultez la section Résoudre des erreurs liées à l’AWS CLI. Vérifiez également que vous utilisez bien la version la plus récente de l'interface.

Utiliser le dossier d’exploitation automatique pour résoudre les erreurs

Avant que le dossier d'exécution AWSSupport-TroubleshootAPIGatewayHttpErrors n'analyse Amazon CloudWatch Logs, il valide l'API, la ressource, l'opération et l'étape.

Accorder les autorisations requises

Avant d'exécuter le dossier d’exploitation, assurez-vous que votre utilisateur ou votre rôle AWS Identity and Access Management (IAM) dispose des autorisations appropriées. Vérifiez que votre utilisateur ou votre rôle IAM est autorisé à accéder au dossier d’exploitation.

En outre, l'utilisateur IAM ou le rôle de service endossé qui exécute l'automatisation doit disposer des autorisations suivantes :

• apigateway:GET
• logs:GetQueryResults
• logs:StartQuery
• ssm:DescribeAutomationExecutions
• ssm:GetAutomationExecution
• ssm:DescribeAutomationStepExecutions
• ssm:StartAutomationExecution
• ssm:DescribeDocument
• ssm:GetDocument
• ssm:ListDocuments

Exécuter l'automatisation

Procédez comme suit :

1. Ouvrez le dossier d’exploitation AWSSupport-TroubleshootAPIGatewayHttpErrors.
2. Sélectionnez Exécuter l'automatisation.
   Saisissez les informations suivantes dans les paramètres d'entrée :
   RestApiId : ID de l'API que vous êtes en train de résoudre.
   StageName : Nom de l'étape déployée.
   ResourcePath : Chemin des ressources de l'opération.
   HttpMethod : Méthode pour le chemin de ressource configuré.
   StartTime : Date et heure de début d’interrogation des journaux CloudWatch. Le format doit être aaaa-MM-jjTHH:mm:ss et le fuseau horaire doit être UTC.
   EndTime : Date et heure de fin d’arrêt d’interrogation des journaux CloudWatch. Le format doit être aaaa-MM-jjTHH:mm:ss et le fuseau horaire doit être UTC.
   AccessLogs : Journaux d'accès que vous souhaitez que le dossier d’exploitation analyse.
   ExecutionId : ID d'exécution de la requête qui présente des erreurs.
   AutomationAssumeRole : ARN du rôle IAM qui permet à Automation d'effectuer les actions en votre nom. Si vous ne spécifiez aucun rôle, Automation utilise les autorisations de l'utilisateur qui lance le dossier d’exploitation.
   StageName : Nom de l'étape déployée.
3. Sélectionnez Exécuter.
4. Consultez la section Sorties pour obtenir des résultats détaillés.
   Remarque : L'automatisation se termine correctement, même lorsque le dossier d’exploitation ne trouve pas de journaux.

Résoudre manuellement les erreurs de code de statut 5xx

Remarque : La résolution suivante s'applique uniquement aux API REST.

Avant de commencer, activez Amazon CloudWatch Logs pour résoudre les erreurs d'API Gateway. Pour détecter les erreurs 5xx dans vos journaux d'exécution, consultez la section Comment détecter les erreurs d'API REST API Gateway dans mes journaux CloudWatch ? La métrique5XXError d’API Gateway capture le nombre d'erreurs côté serveur au cours d'une période spécifiée.

Erreurs dans le code de la fonction Lambda

Pour les erreurs 500 de point de terminaison d'API qui s'intègrent à AWS Lambda, consultez la section Modèles de gestion des erreurs dans Amazon API Gateway et AWS Lambda.

Autorisations manquantes pour une variable d'étape

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

Mappage du code de statut HTTP incorrect ou manquant

Pour résoudre ce problème, configurez des intégrations fictives dans API Gateway.

Problèmes de limitation

Si un nombre élevé de requêtes limite le service de backend, l'API API Gateway peut renvoyer une erreur de serveur interne. Pour résoudre ce problème, activez un backoff exponentiel et un mécanisme de nouvelle tentative, puis essayez d'exécuter à nouveau la requête. Si le problème persiste, vérifiez votre quota API Gateway. Si vous dépassez la limite de quota de service, vous pouvez demander une augmentation de quota de service.

Méthode HTTP non définie de POST

Pour l'intégration Lambda, vous devez utiliser la méthode HTTP POST pour la requête d'intégration. Exécutez la commande put-integration de l’AWS CLI pour mettre à jour la requête 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

Remarque : Remplacez rest-api-id par votre ID d’API REST, resource-id par votre ID de ressource et l'exemple d'URI par votre URI.

Exécutez ensuite la commande create-deployment suivante de l’interface de la ligne de commande AWS pour déployer l'API REST :

aws apigateway create-deployment \
    --rest-api-id id \
    --stage-name stage-resource

Remarque : Remplacez rest-api-id par votre ID d'API REST et stage-resource par votre ressource d’étape pour la ressource de déploiement à créer.

Autorisations Lambda

Assurez-vous que la politique basée sur les ressources de la fonction Lambda intégrée ou du mécanisme d’autorisation Lambda inclut des autorisations permettant à votre API d'invoquer la fonction.

Problème de format JSON de sortie de la fonction Lambda

Si la sortie de votre fonction Lambda intégrée n'est pas conforme au format JSON spécifié pour les API REST, vous recevez un message d'erreur. Assurez-vous d'utiliser le format JSON correct pour la sortie des fonctions Lambda pour les intégrations de proxy et des mécanismes d’autorisation Lambda. Utilisez les exemples de formats JSON suivants.

Exemple de fonction Lambda pour l'intégration de proxy :

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headerName": "headerValue", ... },
    "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
    "body": "..."
}

Exemple de mécanisme d'autorisation Lambda :

{
   "principalId": "user",
  "policyDocument": {
    "Version": "2012-10-17",
    "Statement": [
      { "Action": "execute-api:Invoke",
        "Effect": "Deny",
        "Resource": "arn:aws:execute-api:us-west-2:123456789012:ymy8tbxw7b/dev/GET/"
      }
    ]
  }
}

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

Le quota d'API HTTP maximum pour une taille de charge utile de backend est de 10 Mo. Vous ne pouvez pas augmenter la taille. Assurez-vous donc que la taille de la charge utile du backend ne dépasse pas le quota de 10 Mo.

Intégration de points de terminaison privés

Si vous utilisez un point de terminaison d'API privé, vous devez également configurer l'intégration privée d’API Gateway.

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 de code de statut 502 : Passerelle erronée

Vous recevez un code de statut 502 Passerelle erronée lorsqu'API Gateway ne peut pas traiter la réponse en tant que passerelle ou proxy. Pour résoudre ce problème, consultez la section Comment résoudre les erreurs HTTP 502 provenant des API REST d’API Gateway avec intégration de proxy Lambda ?

Remarque : Lorsqu’API Gateway lit la réponse du service de backend, 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 API Gateway.

Erreur de code de statut 503 : Service indisponible

Une erreur de code de statut 503 se produit car l'intégration du backend n'est pas disponible et l'API API Gateway ne reçoit donc pas de réponse.

Cette erreur peut s'afficher pour les raisons suivantes :

• Le serveur de backend a dépassé sa capacité et ne peut pas traiter les nouvelles requêtes des clients.
• Le serveur de backend est en cours de maintenance temporaire.

Pour résoudre ce problème, vous pouvez ajouter des ressources supplémentaires au serveur de backend et activer un backoff exponentiel et un mécanisme de nouvelle tentative sur le client. Puis, essayez à nouveau la requête.

Erreur de code de statut 504 : Le délai de la requête 504 sur le point de terminaison a expiré

Si une requête d'intégration prend plus de temps que le paramètre de délai d'intégration maximal de votre API REST de l’API Gateway, API Gateway renvoie un code de statut HTTP 504. Pour résoudre cette erreur, consultez la section Comment puis-je résoudre les erreurs de délai d'attente de l'API HTTP 504 avec API Gateway ?

Informations connexes

AWS Support Automation Workflows (SAW)

Bonnes pratiques de sécurité dans Amazon API Gateway

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

Comment puis-je activer CloudWatch Logs pour résoudre les problèmes liés à mon API REST API Gateway ou à mon API WebSocket ?