All Products
Search

This Product

    Object Storage Service:Use HTTP Range requests to get OSS resources in segments

    Document Center

    Object Storage Service:Use HTTP Range requests to get OSS resources in segments

    Last Updated:Mar 20, 2026

    HTTP Range requests let you download a specific byte range from an OSS object instead of the entire file. This is useful for large file downloads (over 100 MB) where network interruptions can cause a full transfer to fail, and for parallel segmented downloads and video streaming.

    This document may contain information about third-party products. This information is for reference only. Alibaba Cloud makes no representations or warranties of any kind, express or implied, about the performance, reliability, or potential impact of using third-party products.

    How it works

    Add a Range header to a GET request. OSS returns only the requested byte range.

    GET /ObjectName HTTP/1.1
Host: <bucket>.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 17 Nov 2015 17:27:45 GMT
Authorization: <SignatureValue>
Range: bytes=<ByteRange>

    OSS responds based on whether the range is valid:

    ConditionStatusDescription
    Valid range206 Partial ContentResponse includes a Content-Range header
    Invalid or out-of-range (default)200 OKOSS ignores the Range header and returns the full object

    To check an object's size before constructing your range, send a HeadObject request. The valid byte range for any object is 0 to Content-Length - 1.

    Range syntax

    All examples below use a 1,000-byte object (valid range: 0–999).

    Bytes from a start offset to an end offset

    Range: bytes=<start>-<end>

    Returns bytes from start through end, inclusive. Both values must fall within the valid range.

    ExampleReturnsStatus
    Range: bytes=0-499Bytes 0–499 (500 bytes)206 Partial Content
    Range: bytes=500-999Bytes 500–999 (500 bytes)206 Partial Content
    Range: bytes=0-1000End byte exceeds object size — full object returned200 OK
    Range: bytes=1000-2000Start byte exceeds object size — full object returned200 OK
    Range: byte=0-499 is invalid — byte must be spelled bytes.

    Bytes from a start offset to the end of the object

    Range: bytes=<start>-

    Returns bytes from start through the end of the object.

    ExampleReturnsStatus
    Range: bytes=500-Bytes 500–999 (500 bytes)206 Partial Content
    Range: bytes=1000-Start byte exceeds object size — full object returned200 OK

    Last N bytes

    Range: bytes=-<N>

    Returns the last N bytes of the object. If N is larger than the object size, the full object is returned.

    ExampleReturnsStatus
    Range: bytes=-500Bytes 500–999 (last 500 bytes)206 Partial Content
    Range: bytes=-2000Full object (N exceeds object size)200 OK

    Full object

    Range: bytes=0-

    Returns the content from the first byte to the last byte, which is the entire file.

    Multiple ranges (up to 50)

    OSS supports requesting up to 50 byte ranges in a single GET request. Add the x-oss-multi-range-behavior: multi-range request header and specify ranges as a comma-separated list.

    GET /ObjectName
x-oss-multi-range-behavior: multi-range
Range: bytes=0-1,3-4,5-6,7-8
Host: <bucket>.oss-cn-hangzhou.aliyuncs.com

    Compatible behavior

    By default, OSS silently ignores an out-of-range Range header and returns the full object with status 200 OK. To get stricter, RFC-compliant behavior instead, add the x-oss-range-behavior: standard request header.

    With compatible behavior enabled, out-of-range requests are handled as follows for a 1,000-byte object (valid range: 0–999):

    RangeBehaviorStatus
    bytes=500-2000End byte exceeds valid range. Returns bytes 500–999.206 Partial Content
    bytes=1000-2000Start byte exceeds valid range. Returns InvalidRange error.416 Requested Range Not Satisfiable
    bytes=1000-Start byte exceeds valid range. Returns InvalidRange error.416 Requested Range Not Satisfiable
    bytes=-2000N exceeds object size. Returns the full object (bytes 0–999).206 Partial Content

    If you receive a 416 error, see OSS 416 error for troubleshooting. The error response body is:

    <?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>InvalidRange</Code>
  <Message>The requested range cannot be satisfied</Message>
  <RequestId>5DA963F7CEBFAA3931BF91F5</RequestId>
  <HostId>bucket.oss-cn-hangzhou.aliyuncs.com</HostId>
  <ActualObjectSize>1000</ActualObjectSize>
  <RangeRequested>bytes=1000-2000</RangeRequested>
</Error>

    Examples

    All examples use a 1,000-byte object (valid range: 0–999).

    Download bytes 0–499

    Request:

    GET /ObjectName
Range: bytes=0-499
Host: bucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 18 Oct 2019 02:51:30 GMT
Authorization: Signature

    Response:

    206 Partial Content
Content-Length: 500
Content-Range: bytes 0-499/1000
Connection: keep-alive
ETag: "CACF99600561A31D494569C979E6FB81"
x-oss-request-id: 5DA928B227D52731327DE078
Date: Fri, 18 Oct 2019 02:51:30 GMT
[500 bytes of object data]

    Download from byte 500 to end of object

    Request:

    GET /ObjectName
Range: bytes=500-
Host: bucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 18 Oct 2019 03:24:39 GMT
Authorization: Signature

    Response:

    206 Partial Content
Content-Length: 500
Content-Range: bytes 500-999/1000
ETag: "CACF99600561A31D494569C979E6FB81"
x-oss-request-id: 5DA9307750EBE33332E3720A
Date: Fri, 18 Oct 2019 03:24:39 GMT
[500 bytes of object data]

    Download the last 500 bytes

    Request:

    GET /ObjectName
Range: bytes=-500
Host: bucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 18 Oct 2019 03:23:22 GMT
Authorization: Signature

    Response:

    206 Partial Content
Content-Length: 500
Content-Range: bytes 500-999/1000
ETag: "CACF99600561A31D494569C979E6FB81"
x-oss-request-id: 5DA9302A6646AC37397F7039
Date: Fri, 18 Oct 2019 03:23:22 GMT
[500 bytes of object data]

    Out-of-range request (default behavior)

    Request with end byte exceeding the valid range:

    GET /ObjectName
Range: bytes=0-1000
Host: bucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 18 Oct 2019 03:00:02 GMT
Authorization: Signature

    Response — OSS ignores the Range header and returns the full object:

    200 OK
Content-Length: 1000
ETag: "CACF99600561A31D494569C979E6FB81"
x-oss-request-id: 5DA92AB204321E36347F3E7D
Date: Fri, 18 Oct 2019 03:00:02 GMT
[1000 bytes of object data]

    Compatible behavior: end byte out of range

    Request with x-oss-range-behavior: standard and end byte outside the valid range:

    GET /ObjectName
x-oss-range-behavior: standard
Range: bytes=500-2000
Host: bucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 18 Oct 2019 07:02:23 GMT
Authorization: Signature

    Response — OSS clips the range to the last valid byte:

    206 Partial Content
Content-Length: 500
Content-Range: bytes 500-999/1000
ETag: "CACF99600561A31D494569C979E6FB81"
x-oss-request-id: 5DA9637FB3B1C73234CC59EB
Date: Fri, 18 Oct 2019 07:02:23 GMT
[500 bytes of object data]

    Compatible behavior: start byte out of range

    Request with x-oss-range-behavior: standard and start byte outside the valid range:

    GET /ObjectName
x-oss-range-behavior: standard
Range: bytes=1000-2000
Host: bucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 18 Oct 2019 07:04:23 GMT
Authorization: Signature

    Response — OSS returns a 416 error:

    416 Requested Range Not Satisfiable
Content-Length: 345
x-oss-request-id: 5DA963F7CEBFAA3931BF91F5
Date: Fri, 18 Oct 2019 07:04:23 GMT
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>InvalidRange</Code>
  <Message>The requested range cannot be satisfied</Message>
  <RequestId>5DA963F7CEBFAA3931BF91F5</RequestId>
  <HostId>bucket.oss-cn-hangzhou.aliyuncs.com</HostId>
  <ActualObjectSize>1000</ActualObjectSize>
  <RangeRequested>bytes=1000-2000</RangeRequested>
</Error>

    Compatible behavior: suffix range exceeding object size

    Request with x-oss-range-behavior: standard and a suffix range larger than the object:

    GET /ObjectName
x-oss-range-behavior: standard
Range: bytes=-2000
Host: bucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 18 Oct 2019 07:06:39 GMT
Authorization: Signature

    Response — OSS returns the full object:

    206 Partial Content
Content-Length: 1000
Content-Range: bytes 0-999/1000
ETag: "CACF99600561A31D494569C979E6FB81"
x-oss-request-id: 5DA9647FC4334F3534AF9A83
Date: Fri, 18 Oct 2019 07:06:39 GMT
[1000 bytes of object data]

    Test with curl

    To verify Range request behavior:

    curl -r 0-100 http://xxxx.oss-cn-hangzhou.aliyuncs.com/xx.zip -o /tmp/xx1.zip -v

    What's next

    • UploadPart — use multipart upload for large file uploads (over 100 MB)

    • HeadObject — retrieve object size before constructing a range request

    • OSS 416 error — troubleshoot InvalidRange errors