When a request to Object Storage Service (OSS) fails, the service returns an error response that includes a standard HTTP status code, a service-specific error code (EC), and a detailed XML body. This topic describes the structure of OSS error responses and outlines strategies for troubleshooting common issues.
Self-troubleshooting process
Step 1: Locate key information
A typical error response contains the information required to diagnose an issue. First, read the Message field for a description of the error. Then, check the following key fields to troubleshoot the issue. The following code provides an example of an error response:
HTTP/1.1 400 Bad Request
Server: AliyunOSS
Date: Thu, 11 Aug 2019 01:44:54 GMT
Content-Type: application/xml
Content-Length: 322
Connection: keep-alive
x-oss-request-id: 57ABD896CCB80C366955****
x-oss-server-time: 0
<?xml version="1.0" encoding="UTF-8"?>
<Error>
<Code>MissingArgument</Code>
<Message>Missing Some Required Arguments.</Message>
<RequestId>57ABD896CCB80C366955****</RequestId>
<HostId>oss-example.oss-cn-hangzhou.aliyuncs.com</HostId>
<EC>0016-00000502</EC>
<RecommendDoc>https://api.aliyun.com/troubleshoot?q=0016-00000502</RecommendDoc>
</Error>RecommendDoc(recommended): A direct link to the official troubleshooting guide for the specific error.EC: A fine-grained error code that corresponds to a specific cause of the error.HTTP status code(such as 400 Bad Request): The general status of the request. You can use this code to determine the general nature of the error (client-side or server-side).RequestId(Required for support): The unique ID of the request. You must provide this ID when you contact technical support.
Step 2: Obtain the solution
Use one of the following methods to find a solution:
Access the
RecommendDoclinkGo to the
RecommendDoclink provided in the error response.
Check the EC error code list
If the response does not contain a
RecommendDoclink, look up theECin the error code list.
If the issue persists, contact technical support with the required information.
To expedite troubleshooting, always provide the full request ID when contacting support. For more information, see Obtain request IDs.
Error response structure
Error response headers
Response header | Description |
| A fine-grained OSS-specific error code. Each error condition maps to a unique EC. Unlike the general-purpose Important The EC field is for diagnostic purposes only. Its value may change without notice, and backward compatibility is not guaranteed. Do not build application logic that depends on specific EC values. |
| The unique ID of the request. Provide this ID when contacting technical support. |
Example of response headers
HTTP/1.1 403 Forbidden
Server: AliyunOSS
Date: Wed, 09 Nov 2022 08:45:46 GMT
Content-Type: application/xml
Content-Length: 471
Connection: keep-alive
x-oss-request-id: 636B68BA80DA8539399F****
x-oss-server-time: 0
x-oss-ec: 0003-00000001For more information, see Common response headers.
Error response body
Element | Description |
| A general-purpose error code defined by OSS. |
| A detailed description of the error. |
| The unique ID of the request. Provide this request ID when you contact technical support to troubleshoot and resolve the issue. |
| Identifies the OSS cluster that handled the request, which corresponds to the host specified in the request. |
| The fine-grained error code, which is the same as the |
| A link to an interactive troubleshooting guide in OpenAPI Explorer for the specific error. Following this link is the recommended first step for troubleshooting. |
Example of a response body
<?xml version="1.0" ?>
<Error xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
<Code>MalformedXML</Code>
<Message>The XML you provided was not well-formed or did not validate against our published schema.</Message>
<RequestId>57ABD896CCB80C366955****</RequestId>
<HostId>oss-cn-hangzhou.aliyuncs.com</HostId>
<EC>0031-00000001</EC>
<RecommendDoc>https://api.aliyun.com/troubleshoot?q=0031-00000001</RecommendDoc>
</Error>