Partager via

Codes d’erreur et gestion des erreurs | Concepts de l’API Graph

  • Article

S’applique à : API Graph | Azure Active Directory (AD)

Les applications clientes qui utilisent l’API Azure Active Directory (AD) Graph doivent implémenter une logique de gestion des erreurs pour réagir le mieux possible aux différentes conditions et offrir la meilleure expérience possible à leurs clients. Cette rubrique présente les types des erreurs renvoyées par l’API Azure AD Graph et fournit des indications d’ordre général sur la façon de les gérer.

Important

Nous vous recommandons fortement d’utiliser Microsoft Graph plutôt que l’API Graph Azure AD pour accéder aux ressources Azure Active Directory. Nos efforts de développement sont désormais axés sur Microsoft Graph et aucune autre amélioration n’est prévue pour l’API Graph Azure AD. Il existe un nombre très limité de scénarios pour lesquels l’API Graph Azure AD peut être encore appropriée ; pour plus d’informations, consultez le billet de blog Microsoft Graph ou l’API Azure AD dans le Centre de développement Office.

Gestion d’erreurs de l’API Graph

Types des erreurs

Les erreurs d’API Graph se produisent dans les catégories suivantes.

  • Erreurs du client. Les erreurs du client sont représentées par les codes d’état HTTP de la série 400. Elles comprennent les objets avec des valeurs non valides, des objets dont les valeurs de propriétés ou propriétés requises sont manquantes, des tentatives d’accès à une ressource inexistante, des tentatives de mise à jour d’une propriété en lecture seule et l’omission du jeton d’autorisation requis. Pour corriger ces erreurs, résolvez le problème sous-jacent avant de retenter la demande.
  • Erreurs du serveur. Les erreurs du serveur sont représentées par les codes d’état HTTP de la série 500, par exemple une défaillance de répertoire temporaire. La plupart de ces erreurs sont temporaires et peuvent être résolues en retentant la demande.
  • Erreurs réseau/de protocole. Différentes erreurs liées au réseau peuvent se produire lors de l’envoi d’une demande ou de la réception d’une réponse, telles que des erreurs de résolution du nom d’hôte, des connexions fermées prématurément et des erreurs de négociation SSL. La plupart de ces erreurs ne peuvent pas être corrigées par une nouvelle tentative ; le problème sous-jacent doit être résolu. Toutefois, certaines erreurs, telles que les échecs de résolution du nom d’hôte ou les délais d’expiration, peuvent être corrigées en retentant la demande.

Structure des messages d’erreur

Les erreurs d’API Graph ont un corps mis en forme qui est constitué d’un code d’état HTTP, d’un message et de valeurs. Utilisez les propriétés du corps d’erreur dans votre logique de gestion des erreurs.

Remarque : toutefois, certaines réponses HTTP peuvent ne pas comporter le corps de réponse code/message/valeurs, car la demande est routée via des services de proxy et de passerelle. Veillez à inclure une logique par défaut qui peut gérer les erreurs en fonction du seul code d’état HTTP.

Voici l’exemple d’une erreur HTTP de la série 400 Request_BadRequest.

 HTTP/1.1 400 Bad Request
 Content-Type: application/json;odata=minimalmetadata;charset=utf-8
 request-id: ddca4a7e-02b1-4899-ace1-19860901f2fc
 Date: Tue, 02 Jul 2013 01:48:19 GMT
 …
 
 {
     "odata.error" : {
         "code" : "Request_BadRequest",
         "message" : {
             "lang" : "en",
             "value" : "A value is required for property 'mailNickname' of resource 'Group'."
         },
     "values" : null
    }
 }

Chaque corps de message dispose de propriétés de code, de message et de valeurs.

  • Code : concevez votre logique de gestion des erreurs pour créer une branche en fonction du code.

    "code" : "Request_BadRequest"

  • Message : tuple langue/valeur qui représente un message d’erreur explicite. Le contenu figure dans le champ valeur. Dans l’exemple suivant, la demande échoue, car la valeur de la propriété mailNickname est manquante.

    "message" : {
     "lang" : "en",
     "value" : "A value is required for property 'mailNickname' of resource 'Group'."
}

  • Valeurs : collection de paires nom/valeur qui fournissent plus d’informations sur la nature de la défaillance. Dans l’exemple suivant, il n’y a pas d’inclusion de valeurs.

    "values" : null

Référence de code d'erreur

Codes d’erreur HTTP

Le tableau suivante répertorie les codes d’erreur, les messages d’erreur et les actions de l’API Graph à prendre en compte pour corriger les erreurs.

Généralement, les erreurs HTTP de la série 500 répondent aux nouvelles tentatives, de préférence distribuées sur des intervalles de temps de plus en plus longs (« nouvelle tentative avec un intervalle de temporisation ») et avec un facteur de distribution aléatoire. Les erreurs de la série 400 indiquent un problème qui doit être résolu avant toute nouvelle tentative.

Code d'état HTTP Code d’erreur Message d'erreur Détails
400 Directory_ExpiredPageToken La valeur de jeton de page spécifiée a expiré et ne peut ne plus être incluse dans votre demande.
400 Directory_ResultSizeLimitExceeded La limite de taille du résultat a été dépassée La demande ne peut pas être satisfaite car elle est associée à trop de résultats. Cette erreur se produit très rarement.
400 DomainVerificationCodeNotFound Échec de la vérification du domaine, car le processus de vérification ne peut pas trouver l’enregistrement TXT correspondant au code de vérification.
400 ObjectConflict Le nom de domaine existe déjà dans un domaine non vérifié de cette société.
400 ObjectConflict Le nom de domaine existe déjà dans un domaine vérifié de cette société.
400 ObjectInUse Impossible de supprimer le domaine actuellement référencé par un utilisateur, un groupe ou une application mutualisée.
400 ObjectPendingDeletion Impossible de vérifier un domaine existant en attente de suppression.
400 ObjectPendingTakeover Impossible de supprimer un domaine pendant la prise de contrôle du client.
400 Request_BadRequest Demande incorrecte. Corrigez la demande avant de réessayer. Indique une erreur dans la demande, par exemple, une valeur de propriété non valide ou un argument de requête non pris en charge. Corrigez la demande avant de réessayer.
400 Request_DataContractVersionMissing Le paramètre de version de contrat de données est manquant. Inclure l’api-version (version de l’API) comme paramètre de demande avec toutes vos demandes.
400 Request_InvalidDataContractVersion L’api-version (version de l’API) spécifiée n'est pas valide. La valeur doit correspondre exactement à une version prise en charge.
400 Request_InvalidRequestUrl L’URL de la demande n’était pas valide. La demande doit avoir le format suivant : /tenantdomainname/Entity ou /$metadata. Le nom de domaine du locataire peut être l’un des noms de domaine vérifiés ou non vérifiés ou d’ID de contexte.
400 Request_UnsupportedQuery La demande GET n’est pas prise en charge. Corrigez les paramètres de la demande et réessayez.
401 Authentication_ExpiredToken Votre jeton d’accès a expiré. Renouvelez-le avant d’envoyer la demande. Le jeton d’accès a expiré. Remplacez le jeton puis resoumettez-le.
401 Authentication_MissingOrMalformed Jeton d’accès manquant ou incorrect. La valeur access_token dans l’en-tête d’autorisation est manquante ou incorrecte. Cette valeur est obligatoire. Utilisez la valeur dans le jeton d’authentification.
401 Authorization_IdentityDisabled Le principal d’application appelant est désactivé. Le principal spécifié dans le jeton d’accès est dans le répertoire, mais est désactivé. Réactivez le compte dans le répertoire, et réessayez.
401 Authorization_IdentityNotFound L’identité de l’application appelante n’a pas pu être établie. Le principal spécifié dans le jeton d’accès est introuvable dans le répertoire. Cela peut être dû au fait que le jeton est périmé, que le principal a été supprimé du répertoire, ou que la synchronisation du répertoire est retardée.
403 Authentication_Unauthorized Demande non autorisée. Le jeton contient des revendications non valides ou non prises en charge. Obtenez un autre jeton et retentez la demande.
403 Authorization_RequestDenied Les informations d’identification spécifiées n’ont pas de privilèges suffisants pour effectuer cette demande. La demande est refusée en raison de privilèges insuffisants. Par exemple, un principal non-administrateur n’est pas autorisé à supprimer une ressource.
403 Directory_QuotaExceeded La limite du quota d’objets d’annuaire pour {tenantName} a été dépassée. Demandez à votre administrateur d’augmenter la limite de quota ou de supprimer des objets pour réduire le quota utilisé. Un quota de répertoire a été dépassé. Le locataire a trop d’objets, ou bien les objets contiennent trop de valeurs. Cela se produit également lorsque trop d’objets sont créés pour le principal. Augmentez le nombre maximum d’objets autorisés pour le locataire ou le principal, ou réduisez le nombre de valeurs comprises dans la demande de création/mise à jour.
404 Directory_ObjectNotFound Impossible de lire les informations de la société à partir du répertoire.
404 Request_ResourceNotFound La ressource {resource} n’existe pas ou l’un de ses objets de référence-propriété interrogés n’est pas présent. La ressource identifiée par l’URI n’existe pas. Modifiez la valeur et retentez la demande.
409 Request_MultipleObjectsWithSameKeyValue Une seule ressource était attendue pour le résultat, mais plusieurs ressources ont été trouvées. Mettez à jour l’objet/les objets pour résoudre le conflit. Cette erreur peut se produire lorsqu’il y a deux objets ou plus qui ont la même valeur de clé, par exemple, lorsque deux utilisateurs ont le même UserPrincipalName.
429 Trop de demandes. Cette erreur est générée lorsque des demandes sont limitée. Un délai d’attente suggérée est retourné dans la valeur Retry-After de l’en-tête de réponse. Relancez la requête après avoir attendu le nombre recommandé de secondes.
500 Service_InternalServerError Le serveur a rencontré une erreur interne. Erreur interne du serveur lors du traitement de la demande.
502 [Tout] « ... Service indisponible… » Un serveur agissant comme une passerelle ou un proxy a rencontré une erreur due à un autre serveur pendant le traitement de la demande. Attendez quelques minutes puis retentez la demande.
503 Directory_ConcurrencyViolation Erreur due aux demandes simultanées envoyées au locataire. Patientez un instant et réessayez.
503 Une erreur s’est produite pendant la vérification DNS. Remarque : Cette erreur peut se produire pour diverses raisons, notamment l’indisponibilité du DNS.
Authentication_Unknown Erreur de serveur interne. Ce code d’erreur est utilisé lorsque d’autres codes d’erreur ne s’appliquent pas.
Authentication_UnsupportedTokenType Le type de jeton présenté n’est pas géré. Seuls les jetons de porteur sont pris en charge. Le type de jeton n’est pas pris en charge. Modifiez le type de jeton et retentez la demande.
Directory_BindingRedirection Les informations du locataire ne sont pas disponibles localement. Utilisez les URL suivantes pour obtenir les informations. Lorsque la partition du locataire n’est pas disponible dans le centre de données, les clients doivent se connecter à l’URI renvoyé dans la réponse.
Directory_BindingRedirectionInternalServerError Les informations du locataire ne sont pas disponibles localement. Le serveur a rencontré une erreur interne en essayant de remplir les points de terminaison de centre de données les plus proches. Lorsqu’une exception de redirection obligatoire se produit, la liste des points de terminaison de centre de données les plus proches est remplie pour le service. Cette erreur signale une exception pendant le remplissage de la liste. Réexécutez la requête.
Directory_CompanyNotFound Impossible de lire les informations de la société à partir du répertoire. Une erreur s’est produite lors du chargement des informations de la société à partir du service d’annuaire.
Directory_ReplicaUnavailable Le réplica par défaut n’est pas disponible. Réessayez sans en-tête de clé de session de réplica. Omettez l’en-tête x-ms-replica-session-key puis réessayez.
Headers_DataContractVersionMissing L’en-tête de version de contrat de données est manquant. Incluez x-ms-dirapi-data-contract-version dans votre demande. La version de contrat cliente est manquante de la demande.
Headers_HeaderNotSupported L’en-tête {0} n’est pas pris en charge actuellement. La demande contient un en-tête HTTP non pris en charge. Modifiez l’en-tête et réessayez la demande.
Request_InvalidReplicaSessionKey La clé de session de réplica fournie n’est pas valide. Résolvez la clé de session de réplica et réessayez la demande.
Request_ThrottledPermanently Votre requête est limitée définitivement. Appelez l’assistance pour résoudre le problème. Le locataire a dépassé de façon répétée et persistante la limite de taux de demandes de jeton. Les demandes provenant du locataire sont rejetées jusqu’à ce que le service soit renégocié. Pour obtenir de l’aide, contactez l’assistance Microsoft.

Ressources supplémentaires