Status and error codes

REST API operations for Azure Storage return standard HTTP status codes, as defined in the HTTP/1.1 Status Code Definitions.

API operations can also return detailed error information that the service defines. This error information is returned in the response body.

The body of the error response follows the basic format shown here. The code element indicates the error code string, whereas the message element indicates the error message string.

<?xml version="1.0" encoding="utf-8"?>  
<Error>  
  <Code>string-value</Code>  
  <Message>string-value</Message>  
</Error>  

For version 2017-07-29 and later, failed API operations also return the Azure Storage error code string in a response header.

A particular error response might also include detailed error information to provide the developer with more information. For example, the following error response indicates an invalid query parameter specified on the request URI, and provides additional information about the invalid parameter's name and value, and the reason for the error.

<?xml version="1.0" encoding="utf-8"?>  
<Error>  
  <Code>InvalidQueryParameterValue</Code>  
  <Message>Value for one of the query parameters specified in the request URI is invalid.</Message>  
  <QueryParameterName>popreceipt</QueryParameterName>  
  <QueryParameterValue>33537277-6a52-4a2b-b4eb-0f905051827b</QueryParameterValue>  
  <Reason>invalid receipt format</Reason>  
</Error>  

For version 2024-08-04 and later, error response will include detailed error information when Account SAS's signed resource type doesn't match the resource being accessed. For example, the following error response indicates the signed resource type 'o' is required to perform the operation.

<?xml version="1.0" encoding="utf-8"?>
<Error>
  <Code>AuthorizationResourceTypeMismatch</Code>
  <Message>This request is not authorized to perform this operation using this resource type. RequestId:42a48a49-201e-0092-3770-a7ea70000000 Time:2024-05-16T09:04:16.3226200Z</Message>
  <ExtendedErrorDetail>SignedResourceTypes 'o' is required to perform this operation.</ExtendedErrorDetail>
</Error>

The following list of articles provide collections of error codes that you might find useful:

• Common REST API error codes

• Blob Storage error codes

• Queue Storage error codes

• Table Storage error codes

• Azure Files error codes

Copy API Error Response

The error response for the Copy APIs follows the same format as previously mentioned. The body of the error response contains the code element for the error code string and the message element indicating the error message string.

For versions 2024-02-04 and later, the error response might include a detailed error if the Copy operation fails due to an issue with the copy source, provided the failure from the source returns this information. The response might include CopySourceStatusCode indicating the status code of the copy source operation, CopySourceErrorCode specifying the x-ms-error-code returned in the copy source's error response and CopySourceErrorMessage indicating the corresponding error message.

<?xml version="1.0" encoding="utf-8"?>  
<Error>  
  <Code>CannotVerifyCopySource</Code>  
  <Message> The specified blob doesn’t exist.
      RequestId:de1e2279-b01e-0000-5f26-5c4741000000
      Time:2023-03-21T18:52:10.1018932Z</Message>
  <CopySourceStatusCode> 404 </CopySourceStatusCode>
  <CopySourceErrorCode> BlobNotFound </CopySourceErrorCode>
  <CopySourceErrorMessage> The specified blob doesn’t exist </CopySourceErrorMessage> 
</Error>  

For versions 2024-02-04 and later, Azure Storage returns the copy source status code and error code in the response header, if they're received in the copy source failure.

The following Copy APIs return these details -

• Copy Blob

• Copy Blob from URL

• Put Blob from URL

• Put Block from URL

• Put Page from URL

• Incremental Copy Blob

• Append Block from URL

• Put Range from URL

• Copy File

Error responses for Table Storage

Error responses for Table Storage comply with the error format described in section 19 of the OData specification. Detailed error information might be included, but the error response always complies with the OData spec.

Batch error responses are similar to standard Table Storage error responses. For more information, see Performing entity group transactions.

The following example shows the basic error body in JSON format (version 2013-08-15 and later):

{"odata.error":{"code":"ResourceNotFound","message":{"lang":"en-US","value":"The specified resource does not exist.\nRequestId:102a2b55-eb35-4254-9daf-854db78a47bd\nTime:2014-06-04T16:18:20.4307735Z"}}}  
  

The following sample shows the basic error body in Atom format (versions 2015-12-11 and earlier):

<?xml version="1.0" encoding="utf-8"?>  
<error xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">  
  <code>ResourceNotFound</code>  
  <message xml:lang="en-US">The specified resource does not exist.  
RequestId:e288ba1e-f5dd-4014-9e09-f1263d223dec  
Time:2014-06-04T16:18:20.7088013Z</message>  
</error>  
  

See also

Troubleshooting API operations
HttpStatusCode enumeration
Storage services REST