Edit

Share via

Microsoft Graph error responses and resource types

  • Article

Errors in Microsoft Graph are returned using standard HTTP status codes, and a JSON error response object.

HTTP status codes

The following table lists and describes the HTTP status codes that can be returned.

Status code Status message Description
400 Bad Request Can't process the request because it's malformed or incorrect.
401 Unauthorized Required authentication information is either missing or not valid for the resource.
402 Payment Required The payment requirements for the API haven't been met.
403 Forbidden Access is denied to the requested resource. The user might not have enough permission or might not have a required license.

Important: If conditional access policies are applied to a resource, an HTTP 403; Forbidden error=insufficient_claims message may be returned. For more information on Microsoft Graph and conditional access, see Developer Guidance for Microsoft Entra Conditional Access.
404 Not Found The requested resource doesn’t exist.
405 Method Not Allowed The HTTP method in the request isn't allowed on the resource.
406 Not Acceptable This service doesn’t support the format requested in the Accept header.
409 Conflict The current state conflicts with what the request expects. For example, the specified parent folder might not exist.
410 Gone The requested resource is no longer available at the server.
411 Length Required A Content-Length header is required on the request.
412 Precondition Failed A precondition provided in the request (such as an if-match header) doesn't match the resource's current state.
413 Request Entity Too Large The request size exceeds the maximum limit.
415 Unsupported Media Type The content type of the request is a format that isn't supported by the service.
416 Requested Range Not Satisfiable The specified byte range is invalid or unavailable.
422 Unprocessable Entity Can't process the request because it is semantically incorrect.
423 Locked The resource that is being accessed is locked.
429 Too Many Requests Client application has been throttled and shouldn't attempt to repeat the request until an amount of time has elapsed.
500 Internal Server Error There was an internal server error while processing the request.
501 Not Implemented The requested feature isn’t implemented.
503 Service Unavailable The service is temporarily unavailable for maintenance or is overloaded. You may repeat the request after a delay, the length of which may be specified in a Retry-After header.
504 Gateway Timeout The server, while acting as a proxy, didn't receive a timely response from the upstream server it needed to access in attempting to complete the request.
507 Insufficient Storage The maximum storage quota has been reached.
509 Bandwidth Limit Exceeded Your app has been throttled for exceeding the maximum bandwidth cap. Your app can retry the request again after more time has elapsed.

The error response is a single JSON object that contains a single property named error. This object includes all the details of the error. You can use the information returned here instead of or in addition to the HTTP status code. The following is an example of a full JSON error body.

{
  "error": {
    "code": "badRequest",
    "message": "Uploaded fragment overlaps with existing data.",
    "innerError": {
      "code": "invalidRange",
      "request-id": "request-id",
      "date": "date-time"
    }
  }
}

Error resource type

The error resource is returned whenever an error occurs in the processing of a request.

Error responses follow the definition in the Microsoft REST API Guidelines.

JSON representation

The error resource is composed of a single resource:

{
  "error": {
    "code": "string",
    "message": "string",
    "innererror": { 
      "code": "string"
    },
    "details": []
  }
}
Property name Value Description
code string An error code string for the error that occurred
message string A developer ready message about the error that occurred. This shouldn't be displayed to the user directly.
innererror error object Optional. An additional error object that might be more specific than the top-level error.
details error object Optional. A list of additional error objects that might provide a breakdown of multiple errors encountered while processing the request.

Properties

The code property contains a machine-readable value that you can take a dependency on in your code.

The innererror object might recursively contain more innererror objects with additional, more specific error codes properties. When handling an error, apps should loop through all the nested error codes that are available and use the most detailed one that they understand.

The message property is a human-readable value that describes the error condition. Don't take any dependency on the content of this value in your code.

The message property at the root contains an error message intended for the developer to read. Error messages aren't localized and shouldn't be displayed directly to the user. When handling errors, your code shouldn't take any dependency on the message property values because they can change at any time, and they often contain dynamic information specific to the failed request. You should only code against error codes returned in code properties.

The details property is an optional array of error objects that have the same JSON format as the top-level error object. In the case of a request that is composed of multiple operations, such as a bulk or batch operation, it might be necessary to return an independent error for each operation. In this case, the details list is populated with these individual errors.