Error codes and error handling | Graph API concepts

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.

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.

Additional resources

• Azure AD Graph API reference