HTTP Range Request

Some of our API's support splitting the response body into smaller chunks. This can be especially useful for devices with a small TLS buffer. This is done using a HTTP range request as defined by RFC-7233..

This documentation is applicable for all our API's that contain an Accept-Ranges: bytes header in the response. This can be checked by executing a normal GET or HEAD request on this endpoint. It will also be explicitly stated in the API definition of that endpoint.


In general, only GET endpoints can support HTTP range requests.

If the endpoint supports range requests, the client can request this using specific headers. If the request is successful and would normally return status 200 OK, it will return status 206 Partial Content instead, with only the requested byte range in the response body.


Please note that errors do not have status 200 OK, so the range request will not be applied and the response body may be larger than expected!

There are a couple of known limitations. Please check the segment “Known Limitations“ below for more info.



Rangerequest headerThe range request HTTP header advertises which bytes the client wants to receive in the response body.

Default: no range request
Format: bytes=<range-start>-<range-end>
range-start: An integer indicating the beginning of the request range. The index is 0-based.
range-end: An optional integer indicating the end of the request range. The end is inclusive, so bytes=0-4 would return 5 bytes: 0, 1, 2, 3 and 4.
If omitted, the end of the response body is taken as the end of the range.
(Yes, for response splitting)


Content-Rangeresponse headerThe Content-Range response header advertises which bytes the server has sent in the response body.

Format: bytes <range-start>-<range-end>/<size>
range-start: An integer indicating the beginning of the request range. The index is 0-based.
range-end: An integer indicating the end of the request range. The end is inclusive, so bytes 0-4/100 would return 5 bytes: 0, 1, 2, 3 and 4.
size: The total byte length of the original response.

Example: Content-Range: bytes 1024-2047/3629
Yes when status is 206;

No otherwise
Content-Lengthresponse headerIn the context of range requests, the Content-Length response header always reflects the actual sent response body length in bytes.

The client request Range: bytes=0-1023.
The server responds with Content-Length: 1024 and Content-Range: bytes 0-1023/3629
Accept-Rangesresponse headerThe Accept-Ranges response header advertises whether this endpoint accepts HTTP range requests. The value indicatates the supported unit to define a range.

Only the unit bytes is supported.

If the Accept-Ranges response header is present, but its value is none, range requests are not supported.


The following cURL command demonstrates how HTTP range requests could be used:

curl -i --request GET \
  --url \
  --header 'Accept: application/json' \
  --header 'Range: bytes=0-1023'

This gives the following response:

HTTP/2 206
server: awselb/2.0
date: Mon, 08 Feb 2021 13:13:54 GMT
content-type: application/json; charset=utf-8
content-length: 1024
etag: W/"400-xWQvmq9+I96lV5hagdjlteB5l2o"
content-range: bytes 0-1023/3163
access-control-allow-origin: *
x-powered-by: Express

{"certificate":"-----BEGIN CERTIFICATE-----\nMIIDWjCCAkKgAwIBAgIVAOtPQsvJMiW4AZxB+JI/Y2msvE+OMA0GCSqGSIb3DQEB\nCwUAME0xSzBJBgNVBAsMQkFtYXpvbiBXZWIgU2VydmljZXMgTz1BbWF6b24uY29t\nIEluYy4gTD1TZWF0dGxlIFNUPVdhc2hpbmd0b24gQz1VUzAeFw0yMDA3MDMwNjM5\nMjJaFw00OTEyMzEyMzU5NTlaMB4xHDAaBgNVBAMME0FXUyBJb1QgQ2VydGlmaWNh\ndGUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDkTbzZIePmMoeD1QTj\nqgV0cueKMP1jui4aKF/f46bxOYmy8rfVfbngf/xBQKLWIa3RkgPzdZCOuKLUHU6q\nAOPL102tfkr2UA4EJ7Ddi8PFQESKpyoBrX8fDeabo5iriequvKi2skAUTgr9FlPp\nMLnWNmxEfjFGR7P9jb2EPqnqSkVfC5a8oWP+Y3qS/oI717lYU7rDfR8ZGmmxp+p6\nfgR1a/Y5Zp47mWQZ4J01psMqDCA3WKh3WC5IACuACiJzBdGCJcCpRL9FWoC6YNao\nOK6YpbkhQPEgGXb7Z+JfnelKF9CQdOKrodLBi0zBRuhrxAqAINwtSU7S+LW4wnb1\nyXE/AgMBAAGjYDBeMB8GA1UdIwQYMBaAFCr/xHqxbPxhtRGXodmKCMZ5aljyMB0G\nA1UdDgQWBBQTSiQQOpoWXQ6nZgsss8i1Q/XrBDAMBgNVHRMBAf8EAjAAMA4GA1Ud\nDwEB/wQEAwIHgDANBgkqhkiG9w0BAQsFAAOCAQEAmsh6AJFKknKSFTyqcKwPErQj\nbx1XVvzwH88EINU0/2A4cjG+7jqdiNAQPksZjqvr5gQHn/tBBYOXbfndKxgqNBGk\nM9DFuYV7ABryfYb3jB0BHpw6L3NfTCtBvpXupyqHFZwEnope3ApWHwk


Malformed Range header

If the request Range header is not in the correct format, the server will respond with a 400 Bad Request status and the message “Malformed Range header“.

curl --request GET \
  --url \
  --header 'Accept: application/json' \
  --header 'Range: bytes=yikes'

400 Bad Request

  "statusCode": 400,
  "statusText": "Bad Request",
  "errors": [
      "message": "Malformed Range header: yikes"

Unsatisfiable Range header

If both the range-start and range-end values of the request Range header are outside the available range, the server will respond with a 416 Range Not Satisfiable status and the message “Unsatisfiable Range header“.

curl --request GET \
  --url \
  --header 'Accept: application/json' \
  --header 'Range: bytes=10000-10999'

416 Range Not Satisfiable

  "statusCode": 416,
  "statusText": "Range Not Satisfiable",
  "errors": [
      "message": "Unsatistiable Range header: bytes=10000-10999"

Known Limitations

Multipart ranges
Multipart ranges are not supported and will return the original complete response.

Conditional range requests
Conditional range requests using an If-Range header is not supported and will be ignored.

HEAD requests
Currently, HEAD requests will always have a Content-Length response header of 0, so they can not be used to retrieve the total byte length of the response beforehand.

As a workaround, the total response byte length can be retrieved from the response Content-Range header when doing an HTTP range request. The total byte length is the value after the slash.

For example: In the response header Content-Range: bytes 0-1023/4298 the value 4298 would be the total response byte length.