Table of contents

Codes d’erreur et gestion des erreurs | Concepts de l’API GraphError codes and error handling | Graph API concepts

Jimaco Brannian|Dernière mise à jour: 19/06/2018
|
2 Collaborateurs

S’applique à : API Graph | Azure Active Directory (AD)Applies to: Graph API | 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. Client applications that use the Azure Active Directory (AD) Graph API should implement error handling logic to react as gracefully as possible to varying conditions and provide the best experience possible to their customers.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.The topic discusses the types of errors that the Azure AD Graph API returns and provides general guidance on how to handle them.

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.We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources.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.Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API.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.There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

Gestion d’erreurs de l’API Graph Handling Graph API errors

Types des erreursTypes of errors

Les erreurs d’API Graph se produisent dans les catégories suivantes.Graph API errors occur in the following categories.

  • Erreurs du client.Client Errors.Les erreurs du client sont représentées par les codes d’état HTTP de la série 400.Client errors are represented by 400-series HTTP status codes.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.They include objects with invalid values, objects that are missing required properties or property values, attempting to access a non-existent resource, attempting to update a read-only property, and omitting the required authorization token.Pour corriger ces erreurs, résolvez le problème sous-jacent avant de retenter la demande.To resolve these errors, fix the underlying issue before retrying the request.
  • Erreurs du serveur.Server Errors.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.Server errors are represented by 500-series HTTP status codes, such as a transient directory failure.La plupart de ces erreurs sont temporaires et peuvent être résolues en retentant la demande.Most of these errors are transient and can be resolved by retrying the request.
  • Erreurs réseau/de protocole.Network/Protocol Errors.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.A variety of network-related errors can occur while sending a request or receiving a response, such as host name resolution errors, prematurely closed connections, and SSL negotiation errors.La plupart de ces erreurs ne peuvent pas être corrigées par une nouvelle tentative ; le problème sous-jacent doit être résolu.Most of these errors cannot be resolved by retrying; the underlying issue has to be fixed.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.However, some errors, such as host-name resolution failures or timeouts, might be resolved by retrying the request.

Structure des messages d’erreurError message structure

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.Graph API errors have a formatted body that consists of an HTTP status code, a message, and values.Utilisez les propriétés du corps d’erreur dans votre logique de gestion des erreurs.Use the properties of the error body in your error handling logic.

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.Note: Some HTTP responses might not include the code/message/values response body because the request is routed through proxy and gateway services.Veillez à inclure une logique par défaut qui peut gérer les erreurs en fonction du seul code d’état HTTP.Be sure to include default logic that can handle errors based on the HTTP status code alone.

Voici l’exemple d’une erreur HTTP de la série 400 Request_BadRequest.The following is an example of an HTTP 400 Request_BadRequest error.

 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.Each message body has code, message, and values properties.

  • Code : concevez votre logique de gestion des erreurs pour créer une branche en fonction du code.Code: Design your error-handling logic to branch based on the code.

    "code" : "Request_BadRequest"
    
  • Message : tuple langue/valeur qui représente un message d’erreur explicite.Message: A language/value tuple that represents a human-readable error message.Le contenu figure dans le champ valeur.The content is in the value field.Dans l’exemple suivant, la demande échoue, car la valeur de la propriété mailNickname est manquante.In the following example, the request fails because the value of the mailNickname property is missing.

    "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.Values: A collection of name/value pairs that provide more information about the nature of the failure.Dans l’exemple suivant, il n’y a pas d’inclusion de valeurs.In the following example no values are included.

    "values" : null
    

Référence de code d'erreur Error code reference

Codes d’erreur HTTP HTTP error codes

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.The following table lists Graph API error codes, error messages, and actions to consider when correcting errors.

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.In general, HTTP 500-series errors respond to retries, preferably distributed over increasingly long time intervals ("retry with a back-off interval") and with a random distribution factor.Les erreurs de la série 400 indiquent un problème qui doit être résolu avant toute nouvelle tentative.400-series errors indicate a problem that must be fixed before retrying.

Code d'état HTTPHTTP Status CodeCode d’erreurError codeMessage d'erreurError messageDétailsDetails
400400Directory_ExpiredPageTokenDirectory_ExpiredPageTokenLa valeur de jeton de page spécifiée a expiré et ne peut ne plus être incluse dans votre demande.The specified page token value has expired and can no longer be included in your request.
400400Directory_ResultSizeLimitExceededDirectory_ResultSizeLimitExceededLa limite de taille du résultat a été dépasséeResult Size Limit was ExceededLa demande ne peut pas être satisfaite car elle est associée à trop de résultats.The request cannot be fulfilled because it is associated with too many results.Cette erreur se produit très rarement.This error occurs very infrequently.
400400DomainVerificationCodeNotFoundDomainVerificationCodeNotFoundÉ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.Domain verification fails because the verification process cannot find the TXT record with matching verification code.
400400ObjectConflictObjectConflictLe nom de domaine existe déjà dans un domaine non vérifié de cette société.The domain name already exists in an unverified domain in this company.
400400ObjectConflictObjectConflictLe nom de domaine existe déjà dans un domaine vérifié de cette société.The domain name already exists in a verified domain in this company.
400400ObjectInUseObjectInUseImpossible de supprimer le domaine actuellement référencé par un utilisateur, un groupe ou une application mutualisée.Cannot delete the domain currently referenced by a user, group or multi-tenant application
400400ObjectPendingDeletionObjectPendingDeletionImpossible de vérifier un domaine existant en attente de suppression.Cannot verify a an existing domain which is pending deletion.
400400ObjectPendingTakeoverObjectPendingTakeoverImpossible de supprimer un domaine pendant la prise de contrôle du client.Cannot delete a domain in the process of a tenant takeover
400400Request_BadRequestRequest_BadRequestDemande incorrecte.Bad request.Corrigez la demande avant de réessayer.Please fix the request before retrying.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.Indicates an error in the request, such as an invalid property value or an unsupported query argument.Corrigez la demande avant de réessayer.Fix the request before retrying.
400400Request_DataContractVersionMissingRequest_DataContractVersionMissingLe paramètre de version de contrat de données est manquant.Data contract version parameter is missing.Inclure l’api-version (version de l’API) comme paramètre de demande avec toutes vos demandes.Include api-version as a query parameter with all your requests.
400400Request_InvalidDataContractVersionRequest_InvalidDataContractVersionL’api-version (version de l’API) spécifiée n'est pas valide.The specified api-version is invalid.La valeur doit correspondre exactement à une version prise en charge.The value must exactly match a supported version.
400400Request_InvalidRequestUrlRequest_InvalidRequestUrlL’URL de la demande n’était pas valide.Request url was invalid.La demande doit avoir le format suivant : /tenantdomainname/Entity ou /$metadata.The request should be like /tenantdomainname/Entity or /$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.Tenant domain name can be any of the verified, unverified domain names or context id.
400400Request_UnsupportedQueryRequest_UnsupportedQueryLa demande GET n’est pas prise en charge.The GET request is unsupported.Corrigez les paramètres de la demande et réessayez.Fix the request parameters and try again.
401401Authentication_ExpiredTokenAuthentication_ExpiredTokenVotre jeton d’accès a expiré.Your access token has expired.Renouvelez-le avant d’envoyer la demande.Please renew it before submitting the request.Le jeton d’accès a expiré.Access token has expired.Remplacez le jeton puis resoumettez-le.Renew the token and then resubmit.
401401Authentication_MissingOrMalformedAuthentication_MissingOrMalformedJeton d’accès manquant ou incorrect.Access Token missing or malformed.La valeur access_token dans l’en-tête d’autorisation est manquante ou incorrecte.The access_token value in the authorization header is missing or malformed.Cette valeur est obligatoire.This value is required.Utilisez la valeur dans le jeton d’authentification.Use the value in the authentication token.
401401Authorization_IdentityDisabledAuthorization_IdentityDisabledLe principal d’application appelant est désactivé.The calling application principal is disabled.Le principal spécifié dans le jeton d’accès est dans le répertoire, mais est désactivé.The principal specified in the access token is in the directory, but is it disabled.Réactivez le compte dans le répertoire, et réessayez.Re-enable the account in the directory, and try again.
401401Authorization_IdentityNotFoundAuthorization_IdentityNotFoundL’identité de l’application appelante n’a pas pu être établie.The identity of the calling application could not be established.Le principal spécifié dans le jeton d’accès est introuvable dans le répertoire.The principal specified in the access token was not found in the directory.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.This might occur because the token is stale, the principal was deleted from the directory, or directory synchronization is delayed.
403403Authentication_UnauthorizedAuthentication_UnauthorizedDemande non autorisée.Unauthorized request.Le jeton contient des revendications non valides ou non prises en charge.The token contains invalid or unsupported claims.Obtenez un autre jeton et retentez la demande.Get the request token again and then retry the request.
403403Authorization_RequestDeniedAuthorization_RequestDeniedLes informations d’identification spécifiées n’ont pas de privilèges suffisants pour effectuer cette demande.The specified credentials do not have sufficient privileges to make this request.La demande est refusée en raison de privilèges insuffisants.The request is denied due to insufficient privileges.Par exemple, un principal non-administrateur n’est pas autorisé à supprimer une ressource.For example, a non-administrative principal does not have permission to delete a resource.
403403Directory_QuotaExceededDirectory_QuotaExceededLa limite du quota d’objets d’annuaire pour {tenantName} a été dépassée.The directory object quota limit for the {tenantName} has been exceeded.Demandez à votre administrateur d’augmenter la limite de quota ou de supprimer des objets pour réduire le quota utilisé.Please ask your administrator to increase the quota limit or delete objects to reduce the used quota.Un quota de répertoire a été dépassé.A directory quota has been exceeded.Le locataire a trop d’objets, ou bien les objets contiennent trop de valeurs.The tenant might have too many objects or the objects might have too many values.Cela se produit également lorsque trop d’objets sont créés pour le principal.This also occurs when too many objects are created on for the 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.Increase the maximum allowed object count for the tenant or principal, or reduce the number of values included in the create/update request.
404404Directory_ObjectNotFoundDirectory_ObjectNotFoundImpossible de lire les informations de la société à partir du répertoire.Unable to read the company information from the directory.
404404Request_ResourceNotFoundRequest_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.Resource {resource} does not exist or one of its queried reference-property objects are not present.La ressource identifiée par l’URI n’existe pas.The resource identified by the URI does not exist.Modifiez la valeur et retentez la demande.Revise the value and retry the request.
409409Request_MultipleObjectsWithSameKeyValueRequest_MultipleObjectsWithSameKeyValueUne seule ressource était attendue pour le résultat, mais plusieurs ressources ont été trouvées.A single resource was expected for the result, but multiple resources were found.Mettez à jour l’objet/les objets pour résoudre le conflit.Please update the object(s) to resolve the conflict.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.This error can occur when there are two or more objects that have the same key value, e.g. when two users have the same UserPrincipalName.
429429Trop de demandes.Too Many Requests.Cette erreur est générée lorsque des demandes sont limitée.This error occurs when requests are being throttled.Un délai d’attente suggérée est retourné dans la valeur Retry-After de l’en-tête de réponse.A suggested wait time is returned in the Retry-After value of the response header.Relancez la requête après avoir attendu le nombre recommandé de secondes.Retry the request after waiting the recommended number of seconds.
500500Service_InternalServerErrorService_InternalServerErrorLe serveur a rencontré une erreur interne.Encountered an internal server error.Erreur interne du serveur lors du traitement de la demande.Internal server error while processing the request.
502502[Tout][All]« ... Service indisponible… »“... Service Unavailable...”Un serveur agissant comme une passerelle ou un proxy a rencontré une erreur due à un autre serveur pendant le traitement de la demande.A server acting as a gateway or proxy encountered an error from another server while processing the request.Attendez quelques minutes puis retentez la demande.Wait a few minutes and then retry the request.
503503Directory_ConcurrencyViolationDirectory_ConcurrencyViolationErreur due aux demandes simultanées envoyées au locataire.Error due to concurrent requests being made to the tenant.Patientez un instant et réessayez.Please wait briefly and retry.
503503Une erreur s’est produite pendant la vérification DNS. Remarque : Cette erreur peut se produire pour diverses raisons, notamment l’indisponibilité du DNS.Error encountered during DNS verification (note: Can be caused by various reasons such as DNS is currently down).
Authentication_UnknownAuthentication_UnknownErreur de serveur interne.Internal server error.Ce code d’erreur est utilisé lorsque d’autres codes d’erreur ne s’appliquent pas.This error code is used when other error codes do not apply.
Authentication_UnsupportedTokenTypeAuthentication_UnsupportedTokenTypeLe type de jeton présenté n’est pas géré.The type of token presented is not handled.Seuls les jetons de porteur sont pris en charge.Only bearer tokens are supported.Le type de jeton n’est pas pris en charge.The token type is not supported.Modifiez le type de jeton et retentez la demande.Revise the token type before trying the request again.
Directory_BindingRedirectionDirectory_BindingRedirectionLes informations du locataire ne sont pas disponibles localement.Tenant information is not available locally.Utilisez les URL suivantes pour obtenir les informations.Use the following Urls to get the information.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.When the tenant partition is not available in the datacenter, clients must connect to the URl returned in the response.
Directory_BindingRedirectionInternalServerErrorDirectory_BindingRedirectionInternalServerErrorLes informations du locataire ne sont pas disponibles localement.Tenant information is not available locally.Le serveur a rencontré une erreur interne en essayant de remplir les points de terminaison de centre de données les plus proches.The server encountered an internal error while trying to populate the nearest datacenter endpoints.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.When a binding redirection exception occurs, the list of nearest datacenter endpoints for the service is populated.Cette erreur signale une exception pendant le remplissage de la liste.This error indicates an exception when populating the list.Réexécutez la requête.Try the query again.
Directory_CompanyNotFoundDirectory_CompanyNotFoundImpossible de lire les informations de la société à partir du répertoire.Unable to read the company information from the directory.Une erreur s’est produite lors du chargement des informations de la société à partir du service d’annuaire.An error occurred while loading company information from the directory service.
Directory_ReplicaUnavailableDirectory_ReplicaUnavailableLe réplica par défaut n’est pas disponible.The preferred replica is unavailable.Réessayez sans en-tête de clé de session de réplica.Please retry without any replica session key header.Omettez l’en-tête x-ms-replica-session-key puis réessayez.Omit the x-ms-replica-session-key header and then retry.
Headers_DataContractVersionMissingHeaders_DataContractVersionMissingL’en-tête de version de contrat de données est manquant.The data contract version header is missing.Incluez x-ms-dirapi-data-contract-version dans votre demande.Include x-ms-dirapi-data-contract-version in your request.La version de contrat cliente est manquante de la demande.The client contract version is missing from the request.
Headers_HeaderNotSupportedHeaders_HeaderNotSupportedL’en-tête {0} n’est pas pris en charge actuellement.Header {0} is not currently supported.La demande contient un en-tête HTTP non pris en charge.The request contains an unsupported HTTP header.Modifiez l’en-tête et réessayez la demande.Change the header and try the request again.
Request_InvalidReplicaSessionKeyRequest_InvalidReplicaSessionKeyLa clé de session de réplica fournie n’est pas valide.The replica session key provided is not valid.Résolvez la clé de session de réplica et réessayez la demande.Fix the replica session key and try the request again.
Request_ThrottledPermanentlyRequest_ThrottledPermanentlyVotre requête est limitée définitivement.Your request is throttled permanently.Appelez l’assistance pour résoudre le problème.Please call support to address the issue.Le locataire a dépassé de façon répétée et persistante la limite de taux de demandes de jeton.The tenant repeatedly and persistently exceeded the token request rate limit.Les demandes provenant du locataire sont rejetées jusqu’à ce que le service soit renégocié.Requests from the tenant are rejected until the service is renegotiated.Pour obtenir de l’aide, contactez l’assistance Microsoft.For help, contact Microsoft Support.

Ressources supplémentaires Additional resources

© 2018 Microsoft