103 Early Hints

HTTP response status code 103 Early Hints is an informational HTTP response that can be used by the server to send HTTP headers to a client in advance of a final HTTP response. It is used in conjunction with the Link headers, and it provides the client an opportunity to adjust accordingly.

103 Early Hints is used because HTTP responses often contain links to external resources that need to be fetched before they can be used. It allows the client to load the specified resources in advance, with the hope of decreasing latency.

Usage

When a server includes 103 Early Hints status code, the client can optionally interpret the Link headers and prefetch the specified resources. It is typically used when the server has to spend time processing a HTTP request before sending a final HTTP response. For example, while the server prepares its final HTTP response, the client can spend time rendering images that will ultimately be required.

Important – it’s just a hint

In any system where forecasting is used, it is important to remember that there are no guarantees. When a server returns with 103 Early Hints status code, suggesting that the client fetch specific resources in advance to improve efficiency, it is typically based on a reasonable assumption. It is only once the final HTTP status code is received that the client can fully trust the HTTP headers.

This lack of guarantee can be experienced in two ways; additional Link headers that were not specified may be required, or Link headers that were returned as early hints were ultimately not needed. In the latter case, the consequence is that the client acted on the hint for naught. Theoretically, this additional effort might result in a slower total transaction time.

The lack of guarantee also implies that when the client operates based on an Early Hint, the operations are safe. For example, using a GET method will not change the state that the server is in.

Replacing server push

The 103 Early Hints status code mechanism is slated to replace the server push mechanism, as part of the resource hints framework using rel=preload, in modern browsers. Unlike server push, 103 Early Hints is not dependent on the final HTTP response before the browser can start to fetch the specified resources.

Example

In the following example, the client requests an index.html file, and the server returns with three hints concerning resources that are likely going to be required. The requested file is not returned in the message body because the server is still generating it. At this point, the client has the option to begin loading the resources that are specified by each of the Link directives.

After a short delay, the server returns the final 200 OK response, along with the official Link directives and the index.html in the message body. Notice the differences between the early hints and the final resource list.

Request

GET /index.html HTTP/1.1
Host: www.example.re

Response

HTTP/1.1 103 Early Hints
Link: </style.css>; rel=preload; as=style
Link: </images/logo.svg>; rel=preload; as=image
Link: </videos/instructions_simple.mp4>; rel=preload; as=video

<there is a short pause in the transmission>

HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Content-Length: 100
Link: </style.css>; rel=preload; as=style
Link: </images/logo.svg>; rel=preload; as=image
Link: </images/pro_badge.svg>; rel=preload; as=image
Link: </videos/instructions_advanced.mp4>; rel=preload; as=video

<message body will follow>

The first early hint resource, style.css, will be fetched and processed by the client as early hints, and the same is true for the logo image and the instructions_simple.mp4 video. Both the style sheet and the logo are usable, as-is. The pro_badge image resource indicated in the final HTTP response does not appear in the first, so this is a resource that needs to be fetched by the client upon the final HTTP response.

The instructions_advanced.mp4 video in the Link headers differs from the early hint. In this example the server suggested using early hints that the instructions_simple.mp4 video is required, however the subsequent early hint fetch operation by the client was completed for nothing. Moreover, the newly-specified video needs to be fetched and processed before index.html can be fully rendered and thereby likely increasing the loading time for index.html as two instead of one video had to be fetched.

Code references

.NET

HttpStatusCode.EarlyHints

Go

http.StatusEarlyHints

Symfony

Response::HTTP_EARLY_HINTS

Python3.5+

http.HTTPStatus.EARLY_HINTS

Apache HttpComponents Core

org.apache.hc.core5.http.HttpStatus.SC_EARLY_HINTS

Angular

@angular/common/http/HttpStatusCode.EarlyHints

Takeaway

The 103 Early Hints informational response status code is optional and may be used to reduce latency when loading pages.

However, its effectiveness will vary based on the predictive accuracy of the server. Clients need to perform safe operations that do not change the state of the server, and be able to adjust for differences between the initial and final messages.

Additionally, clients need to ensure the resources specified in the 103 Early Hints response are fetchable.

Finally, it's important to note that the use of 103 Early Hints will not always be beneficial and can even increase loading times if the server fails to accurately predict which resources will be needed for a given page. Proper implementation and testing is needed to ensure that 103 Early Hints is beneficial and used to its fullest potential.