Common error responses and codes

Errors in the OneDrive API are returned using standard HTTP status codes, as well as a JSON error response object. The following HTTP status codes should be expected.

Status code	Status message	Description
400	Bad Request	Cannot process the request because it is malformed or incorrect.
401	Unauthorized	Required authentication information is either missing or not valid for the resource.
403	Forbidden	Access is denied to the requested resource. The user might not have enough permission.
404	Not Found	The requested resource doesn’t exist.
405	Method Not Allowed	The HTTP method in the request is not 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) does not 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 is not supported by the service.
416	Requested Range Not Satisfiable	The specified byte range is invalid or unavailable.
422	Unprocessable Entity	Cannot process the request because it is semantically incorrect.
429	Too Many Requests	Client application has been throttled and should not 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. You may repeat the request after a delay. There may be a Retry-After header.
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 of the details of the error. You may use the information returned here instead of, or in addition to the HTTP status code returned. Here is an example of a full JSON error body.

{
  "error": {
    "code": "invalidRange",
    "message": "Uploaded fragment overlaps with existing data.",
    "innererror": {
      "code": "fragmentOverlap"
    }
  }
}

The code property

The code property contains one of 15 possible values. Your apps must be prepared to handle any one of these errors.

Code	Description
accessDenied	The caller doesn't have permission to perform the action.
activityLimitReached	The app or user has been throttled.
generalException	An unspecified error has occurred.
invalidRange	The specified byte range is invalid or unavailable.
invalidRequest	The request is malformed or incorrect.
itemNotFound	The resource could not be found.
malwareDetected	Malware was detected in the requested resource.
nameAlreadyExists	The specified item name already exists.
notAllowed	The action is not allowed by the system.
notSupported	The request is not supported by the system.
resourceModified	The resource being updated has changed since the caller last read it, usually an eTag mismatch.
resyncRequired	The delta token is no longer valid, and the app must reset the sync state.
serviceNotAvailable	The service is not available. Try the request again after a delay. There may be a Retry-After header.
quotaLimitReached	The user has reached their quota limit.
unauthenticated	The caller is not authenticated.

The innererror object may recursively contain more innererror objects with additional, more specific error codes. When handling an error, apps should loop through all the error codes available and use the most detailed one that they understand. Some of the more detailed codes are listed at the bottom of this page.

To verify that an error object is an error you are expecting, you must loop over the innererror objects, looking for the error codes you expect. For example:

public bool IsError(string expectedErrorCode)
{
    OneDriveInnerError errorCode = this.Error;
    while (null != errorCode)
    {
        if (errorCode.Code == expectedErrorCode)
            return true;
        errorCode = errorCode.InnerError;
    }
    return false;
}

For a complete example for properly handling errors, take a look at OneDrive Error Code Handling.

The message property at the root contains an error message intended for the developer to read. Error messages are not localized and shouldn't be displayed directly to the user. When handling errors, your code should not key off of message 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.

For more information on the resource returned in the error response, see the Error resource type topic.

Detailed error codes

Below are some additional errors that your app may encounter within the nested innererror objects. Apps are not required to handle these, but may if they choose. The service may add new error codes or stop returning old ones at any time, so it is important that all apps be able to handle the basic 15 above.

Code	Description
accessRestricted	Access restricted to the item's owner.
cannotSnapshotTree	Failed to get a consistent delta snapshot. Try again later.
childItemCountExceeded	Max limit on the number of child items was reached.
entityTagDoesNotMatch	ETag does not match the current item's value.
fragmentLengthMismatch	Declared total size for this fragment is different from that of the upload session.
fragmentOutOfOrder	Uploaded fragment is out of order.
fragmentOverlap	Uploaded fragment overlaps with existing data.
invalidAcceptType	Invalid accept type.
invalidParameterFormat	Invalid parameter format.
invalidPath	Name contains invalid characters.
invalidQueryOption	Invalid query option.
invalidStartIndex	Invalid start index.
lockMismatch	Lock token does not match existing lock.
lockNotFoundOrAlreadyExpired	There is currently no unexpired lock on the item.
lockOwnerMismatch	Lock Owner ID does not match provided ID.
malformedEntityTag	ETag header is malformed. ETags must be quoted strings.
maxDocumentCountExceeded	Max limit on number of Documents is reached.
maxFileSizeExceeded	Max file size exceeded.
maxFolderCountExceeded	Max limit on number of Folders is reached.
maxFragmentLengthExceeded	Max file size exceeded.
maxItemCountExceeded	Max limit on number of Items is reached.
maxQueryLengthExceeded	Max query length exceeded.
maxStreamSizeExceeded	Maximum stream size exceeded.
parameterIsTooLong	Parameter Exceeds Maximum Length.
parameterIsTooSmall	Parameter is smaller then minimum value.
pathIsTooLong	Path exceeds maximum length.
pathTooDeep	Folder hierarchy depth limit reached.
propertyNotUpdateable	Property not updateable.
resyncApplyDifferences	Resync required. Replace any local items with the server's version (including deletes) if you're sure that the service was up to date with your local changes when you last sync'd. Upload any local changes that the server doesn't know about.
resyncRequired	Resync is required.
resyncUploadDifferences	Resync required. Upload any local items that the service did not return, and upload any files that differ from the server's version (keeping both copies if you're not sure which one is more up-to-date).
serviceNotAvailable	The server is unable to process the current request.
serviceReadOnly	Resource is temporarily read-only.
throttledRequest	Too many requests.
tooManyResultsRequested	Too many results requested.
tooManyTermsInQuery	Too many terms in the query.
totalAffectedItemCountExceeded	Operation is not allowed because the number of affected items exceeds threshold.
truncationNotAllowed	Data truncation is not allowed.
uploadSessionFailed	Upload session failed.
uploadSessionIncomplete	Upload session incomplete.
uploadSessionNotFound	Upload session not found.
virusSuspicious	This document is suspicious and may have a virus.
zeroOrFewerResultsRequested	Zero or fewer results requested.