Table of contents

Error codes and error handling | Graph API concepts

Jimaco Brannian|Last Updated: 3/28/2018
|
3 Contributors

Applies to: Graph API | Azure Active Directory (AD)

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. The topic discusses the types of errors that the Azure AD Graph API returns and provides general guidance on how to handle them.

Important

We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources. Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API. 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.

Handling Graph API errors

Types of errors

Graph API errors occur in the following categories.

  • Client Errors. Client errors are represented by 400-series HTTP status codes. 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. To resolve these errors, fix the underlying issue before retrying the request.
  • Server Errors. Server errors are represented by 500-series HTTP status codes, such as a transient directory failure. Most of these errors are transient and can be resolved by retrying the request.
  • Network/Protocol Errors. 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. Most of these errors cannot be resolved by retrying; the underlying issue has to be fixed. However, some errors, such as host-name resolution failures or timeouts, might be resolved by retrying the request.

Error message structure

Graph API errors have a formatted body that consists of an HTTP status code, a message, and values. Use the properties of the error body in your error handling logic.

Note: Some HTTP responses might not include the code/message/values response body because the request is routed through proxy and gateway services. Be sure to include default logic that can handle errors based on the HTTP status code alone.

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
    }
 }

Each message body has code, message, and values properties.

  • Code: Design your error-handling logic to branch based on the code.

    "code" : "Request_BadRequest"
    
  • Message: A language/value tuple that represents a human-readable error message. The content is in the value field. 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'."
    }
    
  • Values: A collection of name/value pairs that provide more information about the nature of the failure. In the following example no values are included.

    "values" : null
    

Error code reference

HTTP error codes

The following table lists Graph API error codes, error messages, and actions to consider when correcting errors.

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. 400-series errors indicate a problem that must be fixed before retrying.

HTTP Status CodeError codeError messageDetails
400Directory_ExpiredPageTokenThe specified page token value has expired and can no longer be included in your request.
400Directory_ResultSizeLimitExceededResult Size Limit was ExceededThe request cannot be fulfilled because it is associated with too many results. This error occurs very infrequently.
400DomainVerificationCodeNotFoundDomain verification fails because the verification process cannot find the TXT record with matching verification code.
400ObjectConflictThe domain name already exists in an unverified domain in this company.
400ObjectConflictThe domain name already exists in a verified domain in this company.
400ObjectInUseCannot delete the domain currently referenced by a user, group or multi-tenant application
400ObjectPendingDeletionCannot verify a an existing domain which is pending deletion.
400ObjectPendingTakeoverCannot delete a domain in the process of a tenant takeover
400Request_BadRequestBad request. Please fix the request before retrying.Indicates an error in the request, such as an invalid property value or an unsupported query argument. Fix the request before retrying.
400Request_DataContractVersionMissingData contract version parameter is missing. Include api-version as a query parameter with all your requests.
400Request_InvalidDataContractVersionThe specified api-version is invalid. The value must exactly match a supported version.
400Request_InvalidRequestUrlRequest url was invalid. The request should be like /tenantdomainname/Entity or /$metadata. Tenant domain name can be any of the verified, unverified domain names or context id.
400Request_UnsupportedQueryThe GET request is unsupported. Fix the request parameters and try again.
401Authentication_ExpiredTokenYour access token has expired. Please renew it before submitting the request.Access token has expired. Renew the token and then resubmit.
401Authentication_MissingOrMalformedAccess Token missing or malformed.The access_token value in the authorization header is missing or malformed. This value is required. Use the value in the authentication token.
401Authorization_IdentityDisabledThe calling application principal is disabled.The principal specified in the access token is in the directory, but is it disabled. Re-enable the account in the directory, and try again.
401Authorization_IdentityNotFoundThe identity of the calling application could not be established.The principal specified in the access token was not found in the directory. This might occur because the token is stale, the principal was deleted from the directory, or directory synchronization is delayed.
403Authentication_UnauthorizedUnauthorized request.The token contains invalid or unsupported claims. Get the request token again and then retry the request.
403Authorization_RequestDeniedThe specified credentials do not have sufficient privileges to make this request.The request is denied due to insufficient privileges. For example, a non-administrative principal does not have permission to delete a resource.
403Directory_QuotaExceededThe directory object quota limit for the {tenantName} has been exceeded. Please ask your administrator to increase the quota limit or delete objects to reduce the used quota.A directory quota has been exceeded. The tenant might have too many objects or the objects might have too many values. This also occurs when too many objects are created on for the principal. Increase the maximum allowed object count for the tenant or principal, or reduce the number of values included in the create/update request.
404Directory_ObjectNotFoundUnable to read the company information from the directory.
404Request_ResourceNotFoundResource {resource} does not exist or one of its queried reference-property objects are not present.The resource identified by the URI does not exist. Revise the value and retry the request.
409Request_MultipleObjectsWithSameKeyValueA single resource was expected for the result, but multiple resources were found. Please update the object(s) to resolve the conflict.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.
429Too Many Requests.This error occurs when requests are being throttled. A suggested wait time is returned in the Retry-After value of the response header. Retry the request after waiting the recommended number of seconds.
500Service_InternalServerErrorEncountered an internal server error.Internal server error while processing the request.
502[All]“... Service Unavailable...”A server acting as a gateway or proxy encountered an error from another server while processing the request. Wait a few minutes and then retry the request.
503Directory_ConcurrencyViolationError due to concurrent requests being made to the tenant. Please wait briefly and retry.
503Error encountered during DNS verification (note: Can be caused by various reasons such as DNS is currently down).
Authentication_UnknownInternal server error.This error code is used when other error codes do not apply.
Authentication_UnsupportedTokenTypeThe type of token presented is not handled. Only bearer tokens are supported.The token type is not supported. Revise the token type before trying the request again.
Directory_BindingRedirectionTenant information is not available locally. Use the following Urls to get the information.When the tenant partition is not available in the datacenter, clients must connect to the URl returned in the response.
Directory_BindingRedirectionInternalServerErrorTenant information is not available locally. The server encountered an internal error while trying to populate the nearest datacenter endpoints.When a binding redirection exception occurs, the list of nearest datacenter endpoints for the service is populated. This error indicates an exception when populating the list. Try the query again.
Directory_CompanyNotFoundUnable to read the company information from the directory.An error occurred while loading company information from the directory service.
Directory_ReplicaUnavailableThe preferred replica is unavailable. Please retry without any replica session key header.Omit the x-ms-replica-session-key header and then retry.
Headers_DataContractVersionMissingThe data contract version header is missing. Include x-ms-dirapi-data-contract-version in your request.The client contract version is missing from the request.
Headers_HeaderNotSupportedHeader {0} is not currently supported.The request contains an unsupported HTTP header. Change the header and try the request again.
Request_InvalidReplicaSessionKeyThe replica session key provided is not valid.Fix the replica session key and try the request again.
Request_ThrottledPermanentlyYour request is throttled permanently. Please call support to address the issue.The tenant repeatedly and persistently exceeded the token request rate limit. Requests from the tenant are rejected until the service is renegotiated. For help, contact Microsoft Support.

Additional resources

© 2018 Microsoft