Fix request denied error 0003-00000503 due to hotlink protection - Object Storage Service

Item	Detail
Error code	`0003-00000503`
Error message	Request denied by hotlink protection configuration
Cause	The value of the Referer header in the request is not in the Referer whitelist that is configured for the bucket.

Why this error occurs

This error is returned when the Referer header in your request does not match any pattern in the Referer whitelist configured for the bucket.

Different hotlink protection denial scenarios return different error codes. Error code 0003-00000503 specifically indicates that the Referer value is not in the whitelist. If the Referer is empty or missing, error code 0003-00000501 is returned. If the Referer matches a blacklist entry, error code 0003-00000502 is returned.

Solutions

Option 1: Include an allowed Referer in the request

Update the Referer header in your request so that it matches a pattern in the bucket's Referer whitelist. In the example below, change the Referer from http://test.com to a value that matches http://*.aliyuncs.com, such as http://test.aliyuncs.com.

Option 2: Modify the bucket's Referer configuration

If you are the owner of the bucket, you can modify the Referer configuration of the bucket to allow access from specified Referers. For more information, see Hotlink protection.

Example

Consider a bucket with the following Referer configuration:

<RefererConfiguration>
  <AllowEmptyReferer>false</AllowEmptyReferer>
  <RefererList>
    <Referer>http://*.aliyuncs.com</Referer>
  </RefererList>
  <RefererBlacklist>
    <Referer>http://abc.aliyuncs.com</Referer>
  </RefererBlacklist>
</RefererConfiguration>

This configuration means:

Rule	Effect
`AllowEmptyReferer` = `false`	Requests without a Referer header are denied (error code `0003-00000501`).
Referer whitelist: `http://*.aliyuncs.com`	Only requests whose Referer matches `http://*.aliyuncs.com` are allowed. Requests with a non-matching Referer are denied (error code `0003-00000503`).
Referer blacklist: `http://abc.aliyuncs.com`	Requests from `http://abc.aliyuncs.com` are denied (error code `0003-00000502`), even though the domain matches the whitelist pattern.

Denied request

The following request is denied because the Referer value http://test.com does not match any entry in the Referer whitelist (http://*.aliyuncs.com):

GET /test.txt HTTP/1.1
Date: Tue, 20 Dec 2022 08:48:18 GMT
Host: BucketName.oss-example-endpoint.aliyuncs.com
Referer: http://test.com

Successful request

The following request succeeds because the Referer value http://test.aliyuncs.com matches the whitelist pattern http://*.aliyuncs.com and is not in the Referer blacklist:

GET /test.txt HTTP/1.1
Date: Tue, 20 Dec 2022 08:48:18 GMT
Host: BucketName.oss-example-endpoint.aliyuncs.com
Referer: http://test.aliyuncs.com

Diagnosis

Before you modify any configuration, confirm the root cause by checking the following:

Identify the bucket's current Referer configuration. If you are the bucket owner, review the hotlink protection settings in the OSS console or retrieve them through the API.
Check the Referer header in your request. Verify which Referer value your client is sending. You can use curl with the -v flag to inspect request headers:
```
curl -v http://BucketName.oss-example-endpoint.aliyuncs.com/test.txt
```
Look for the Referer: line in the output. If no Referer header is present, the request is treated as having an empty Referer, which produces a different error code (0003-00000501).
Compare the Referer value against the whitelist. Make sure the Referer in your request matches at least one pattern in the RefererList and does not match any entry in the RefererBlacklist.

Common mistakes

Protocol mismatch. The whitelist entry specifies http:// but the request sends https://, or vice versa. Wildcard patterns like http://*.aliyuncs.com do not match https:// URLs.
Wildcard pattern misunderstanding. The wildcard * in http://*.aliyuncs.com matches subdomains such as http://test.aliyuncs.com, but does not match unrelated domains such as http://test.com.

Security considerations

Referer headers can be spoofed. Hotlink protection relies on the Referer header, which clients can modify. This feature is suitable for preventing casual hotlinking but should not be treated as a strong access control mechanism.
For stronger protection, consider using signed URLs or STS temporary credentials to control access to your OSS resources. These methods provide cryptographic verification and are not susceptible to header spoofing.