Table of contents

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

Jimaco Brannian|Dernière mise à jour: 07/09/2016
|
1 Contributeur

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

La fonctionnalité d’API Azure AD Graph est également disponible au moyen de Microsoft Graph, une API unifiée qui intègre aussi des API d’autres services Microsoft tels que Outlook, OneDrive, OneNote, Planner et Office Graph, tous accessibles par le biais d’un seul point de terminaison à l’aide d’un seul jeton d’accès.

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 HTTPCode d’erreurMessage d'erreurDétails
400Directory_ExpiredPageTokenLa valeur de jeton de page spécifiée a expiré et ne peut ne plus être incluse dans votre demande.
400Directory_ResultSizeLimitExceededLa limite de taille du résultat a été dépasséeLa demande ne peut pas être satisfaite car elle est associée à trop de résultats. Cette erreur se produit très rarement.
400DomainVerificationCodeNotFoundÉ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.
400ObjectConflictLe nom de domaine existe déjà dans un domaine non vérifié de cette société.
400ObjectConflictLe nom de domaine existe déjà dans un domaine vérifié de cette société.
400ObjectInUseImpossible de supprimer le domaine actuellement référencé par un utilisateur, un groupe ou une application mutualisée.
400ObjectPendingDeletionImpossible de vérifier un domaine existant en attente de suppression.
400ObjectPendingTakeoverImpossible de supprimer un domaine pendant la prise de contrôle du client.
400Request_BadRequestDemande 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.
400Request_DataContractVersionMissingLe 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.
400Request_InvalidDataContractVersionL’api-version (version de l’API) spécifiée n'est pas valide. La valeur doit correspondre exactement à une version prise en charge.
400Request_InvalidRequestUrlL’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.
400Request_UnsupportedQueryLa demande GET n’est pas prise en charge. Corrigez les paramètres de la demande et réessayez.
401Authentication_ExpiredTokenVotre 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.
401Authentication_MissingOrMalformedJeton 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.
401Authorization_IdentityDisabledLe 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.
401Authorization_IdentityNotFoundL’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.
403Authentication_UnauthorizedDemande non autorisée.Le jeton contient des revendications non valides ou non prises en charge. Obtenez un autre jeton et retentez la demande.
403Authorization_RequestDeniedLes 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.
403Directory_QuotaExceededLa 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.
404Directory_ObjectNotFoundImpossible de lire les informations de la société à partir du répertoire.
404Request_ResourceNotFoundLa 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.
409Request_MultipleObjectsWithSameKeyValueUne 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.
500Service_InternalServerErrorLe 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.
503Directory_ConcurrencyViolationErreur due aux demandes simultanées envoyées au locataire. Patientez un instant et réessayez.
503Request_ThrottledTemporarilyVotre requête est temporairement limitée. Essayez dans {0} secondes.Le taux de demandes de jeton a atteint la limite gérable par le service. Attendez quelques minutes et retentez la demande en augmentant les intervalles de temporisation. En augmentant la temporisation entre les nouvelles tentatives, la demande aura plus de chances de réussir et le backlog sera éliminé.
503Une erreur s’est produite pendant la vérification DNS. Remarque : Cette erreur peut se produire pour diverses raisons, notamment l’indisponibilité du DNS.
Authentication_UnknownErreur de serveur interne.Ce code d’erreur est utilisé lorsque d’autres codes d’erreur ne s’appliquent pas.
Authentication_UnsupportedTokenTypeLe 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_BindingRedirectionLes 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_BindingRedirectionInternalServerErrorLes 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_CompanyNotFoundImpossible 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_ReplicaUnavailableLe 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_DataContractVersionMissingL’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_HeaderNotSupportedL’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_InvalidReplicaSessionKeyLa 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_ThrottledPermanentlyVotre 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

© 2017 Microsoft