Upload-Offset

The unofficial Upload-Offset header field reports how many bytes of a resumable upload the server has processed, and tells the server where an interrupted transfer continues.

Table of Contents

Usage

The Upload-Offset header field carries a byte count in both directions of a resumable upload exchange.

In responses, the server states how many bytes of the representation have been received and stored. The count appears on 104 interim responses for live progress reporting, on the successful answer to an offset-retrieval HEAD or GET request, and on the 409 response rejecting a mismatched append. A client reading the value releases buffered data, since the acknowledged bytes never need retransmitting.

In requests, the client states the position where an append starts. A PATCH request against the upload resource sets Upload-Offset to the number of bytes the server already holds, and the request content continues from there. The server compares the stated offset with the stored state and rejects any mismatch.

The offset only grows. A server losing part of the stored data deactivates the upload resource instead of reporting a smaller number, so a client never appends against state rewound behind its back. A DELETE request against the upload resource cancels the upload, freeing the stored bytes and deactivating the resource.

Values

The value is a Structured Fields Item holding a non-negative integer: the number of bytes processed so far. An offset of 0 on a fresh upload resource means no content has been stored yet.

Example

The examples leave out the Upload-Draft-Interop-Version handshake, which 104 covers.

A client recovers from a dropped connection by asking the upload resource for the current offset, then appending the remaining bytes.

Request

HEAD /uploads/b3k2pp5k7z HTTP/1.1
Host: www.example.re

Response

HTTP/1.1 204 No Content
Upload-Offset: 1048576
Upload-Complete: ?0
Upload-Length: 1560576
Upload-Limit: max-size=1073741824
Cache-Control: no-store

The server holds the first 1048576 bytes. The client resumes the transfer from the same position.

Request

PATCH /uploads/b3k2pp5k7z HTTP/1.1
Host: www.example.re
Upload-Offset: 1048576
Upload-Complete: ?1
Content-Type: application/partial-upload
Content-Length: 512000

[bytes 1048576 through 1560575]

A stated offset disagreeing with the stored state produces a 409 response, with the mismatching-upload-offset problem type available for the body, naming the expected and provided offsets so the client corrects the next attempt.

See also

Last updated: August 18, 2026