Error codes and error handling | Graph API concepts

  • Article

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.

This article applies to Azure AD Graph API. For similar info related to Microsoft Graph API, see Microsoft Graph error responses and resource types.

Important

Azure Active Directory (Azure AD) Graph is deprecated. Going forward, we will make no further investment in Azure AD Graph, and Azure AD Graph APIs have no SLA or maintenance commitment beyond security-related fixes. Investments in new features and functionalities will only be made in Microsoft Graph.

June 30, 2023 will mark the end of the three-year deprecation period for Azure AD Graph. Before June 30, 2023, existing applications using Azure AD Graph will not be impacted. After June 30, 2023, Azure AD Graph will enter its retirement phase where we will retire it in incremental steps to allow you sufficient time to migrate your applications to Microsoft Graph APIs. The first step in this plan, and at a later date that we will announce, we will block the creation of any new applications using Azure AD Graph.

For more details on the latest announcement, see Important: Azure AD Graph Retirement and Powershell Module Deprecation.

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 Code Error code Error message Details
400 Directory_ExpiredPageToken The specified page token value has expired and can no longer be included in your request.
400 Directory_ResultSizeLimitExceeded Result Size Limit was Exceeded The request cannot be fulfilled because it is associated with too many results. This error occurs very infrequently.
400 DomainVerificationCodeNotFound Domain verification fails because the verification process cannot find the TXT record with matching verification code.
400 ObjectConflict The domain name already exists in an unverified domain in this company.
400 ObjectConflict The domain name already exists in a verified domain in this company.
400 ObjectInUse Cannot delete the domain currently referenced by a user, group or multi-tenant application
400 ObjectPendingDeletion Cannot verify a an existing domain which is pending deletion.
400 ObjectPendingTakeover Cannot delete a domain in the process of a tenant takeover
400 Request_BadRequest Bad 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.
400 Request_DataContractVersionMissing Data contract version parameter is missing. Include api-version as a query parameter with all your requests.
400 Request_InvalidDataContractVersion The specified api-version is invalid. The value must exactly match a supported version.
400 Request_InvalidRequestUrl Request 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.
400 Request_UnsupportedQuery The GET request is unsupported. Fix the request parameters and try again.
401 Authentication_ExpiredToken Your access token has expired. Please renew it before submitting the request. Access token has expired. Renew the token and then resubmit.
401 Authentication_MissingOrMalformed Access 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.
401 Authorization_IdentityDisabled The 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.
401 Authorization_IdentityNotFound The 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.
403 Authentication_Unauthorized Unauthorized request. The token contains invalid or unsupported claims. Get the request token again and then retry the request.
403 Authorization_RequestDenied The 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.
403 Directory_QuotaExceeded The 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.
404 Directory_ObjectNotFound Unable to read the company information from the directory.
404 Request_ResourceNotFound Resource {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.
409 Request_MultipleObjectsWithSameKeyValue A 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.
429 Too 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.
500 Service_InternalServerError Encountered 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.
503 Directory_ConcurrencyViolation Error due to concurrent requests being made to the tenant. Please wait briefly and retry.
503 Error encountered during DNS verification (note: Can be caused by various reasons such as DNS is currently down).
Authentication_Unknown Internal server error. This error code is used when other error codes do not apply.
Authentication_UnsupportedTokenType The 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_BindingRedirection Tenant 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_BindingRedirectionInternalServerError Tenant 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_CompanyNotFound Unable to read the company information from the directory. An error occurred while loading company information from the directory service.
Directory_ReplicaUnavailable The preferred replica is unavailable. Please retry without any replica session key header. Omit the x-ms-replica-session-key header and then retry.
Headers_DataContractVersionMissing The 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_HeaderNotSupported Header {0} is not currently supported. The request contains an unsupported HTTP header. Change the header and try the request again.
Request_InvalidReplicaSessionKey The replica session key provided is not valid. Fix the replica session key and try the request again.
Request_ThrottledPermanently Your 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