HTTP range requests ask a server to return part of a representation rather than the entire resource. They can support resumable downloads and media access, but clients must verify the response and representation identity. Appending bytes from a changed file can produce an invalid result even when each request succeeds.
A reliable design separates partial-transfer syntax, authorization, validators, and final integrity. This guide explains the practical boundaries without assuming every server or intermediary supports ranges in the same way.
Confirm that partial access is useful
Identify the use case: resuming an interrupted export, seeking in media, or another supported client operation. Range behavior should fit the representation and storage system, not be added solely because a header is easy to send.
Review the expected resource size and change behavior. A stable versioned object is easier to resume correctly than a dynamic report regenerated on every request. Define whether the URL identifies one immutable result or current content.
Keep authorization on every partial request. A caller allowed to read one byte range still receives private data. Range handling does not bypass the normal object and tenant permission boundary.
Read supported response behavior
A server can indicate range support and respond with the documented partial-content status and Content-Range information. It can also ignore a range and return a full representation or reject an unsatisfiable request under HTTP rules.
The client must inspect status and headers before deciding how to store the body. A full response should not be blindly appended to an existing partial file. That can duplicate content and conceal corruption.
Range: bytes=1000-1999This illustrates a bounded byte request, not proof the server will honor it. The application must validate the actual response and representation context.
Preserve representation identity
Use supported validators to determine whether the resource matches the previously downloaded version. If-Range can relate a range request to an appropriate validator under documented semantics. Read the restrictions, including weak-validator behavior.
If the representation changed, follow the server’s response and the application’s restart policy. Do not combine an old prefix with a new suffix because the filenames match. A name or URL alone may not identify stable bytes.
Keep encoding and intermediary transformations in scope. Byte ranges apply to a representation, and compressed or transformed content can affect assumptions. Test the actual client, server, and proxy path.
Verify offsets and lengths
Check returned range boundaries and expected byte count according to the response form. An off-by-one error can corrupt a resumed file. Use supported parsers rather than extracting arbitrary digits from a header.
For multiple ranges, the response can have multipart structure. A client expecting one raw byte segment must not treat the entire multipart body as file data. Prefer a simple supported scope unless the product genuinely needs multi-range behavior.
Bound numerical inputs and resource use. Extremely large or numerous ranges can create unnecessary work. Validate requests and use server limits appropriate to the platform rather than accepting arbitrary complexity.
Keep partial-file state controlled
Store partial output in a location with explicit ownership and completion state. Record the representation validator, downloaded extent, and expected final integrity where required. A partial filename should not be presented as a completed business artifact.
Handle overlap, restart, and interruption deliberately. A resumed request can fail again, so the state update must reflect only accepted bytes. Avoid marking the entire requested interval complete before the body has been validated and written.
Protect private temporary files and cleanup policy. A failed download can still contain sensitive content. Retention and access should not depend on whether the final transfer succeeded.
Review caching and signed access
Caches and CDNs can have supported range behavior that affects performance and response assembly. Test the deployed configuration and private-cache policy. A backend unit test cannot establish every intermediary’s behavior.
Short-lived signed URLs can expire between range requests. Obtain a new authorized capability through the approved workflow where necessary, and retain the intended object version. Do not extend access by copying or exposing secret query parameters.
Keep complete capability URLs out of logs. Nonsecret object identity, status, range category, and transfer outcome can support diagnostics without leaking the download permission.
Test whole-file integrity after resume
Use synthetic files with a known approved checksum or content identity. Interrupt the transfer, resume through supported ranges, and verify the final result. Test a changed representation and confirm it restarts or fails according to policy.
Include ignored ranges, unsatisfiable ranges, malformed headers, truncated responses, and multiple-range behavior if supported. The client should not silently accept a status it does not understand.
Test authorization changes between attempts. If access is revoked, a resumed request must obey current policy. A partial file already held by the client is a separate retention question and should be acknowledged in the threat model.
A practical report download
Suppose a private report is generated once and stored under a versioned identity. The client records the validator and accepted byte extent, uses bounded range requests after interruption, and checks response status and boundaries before appending.
If the server returns a new full representation, the client follows its controlled replacement policy rather than appending. If permission is denied, it stops and reports the actual outcome. Completion is published only after integrity and size checks pass.
The design makes resume a verified transfer behavior, not a guess that the next body contains the missing tail.
Document the server-client contract
Record support, validators, encoding assumptions, maximum range complexity, private access, and final verification. Review the contract when storage or CDN configuration changes.
Monitor partial-transfer failures and repeated restarts. They can reveal an unstable representation or incompatible intermediary. Fix the demonstrated path instead of disabling every validation check to make downloads appear successful.
Frequently asked questions
Can a server return the whole file after a range request?
Yes, under supported behavior. Inspect the response rather than blindly appending its body.
Is the same URL enough to identify unchanged bytes?
Not always. Use an appropriate representation identity and validator policy.
Where can I check status and header rules?
Read MDN’s HTTP range requests guide. For download presentation separately, see our Content-Disposition guide.
