Study on the design differences between HTTP/2 and HTTP/3 from the missing phrases caused by HTTP.

introduction

Handling HTTP error responses is a common task when developing web applications, especially when capturing and presenting error messages to users. However, when using the HTTP/2 and HTTP/3 protocols, you may notice that you cannot get the HTTP status text directly (such as "Bad Request") and only get the status code (such as 400). This article will explore in-depth the reasons for this phenomenon, the design intentions behind it, and how to deal with this situation gracefully on the client.

background

In one debugging, I found that using jQuery$.ajaxWhen the method is in error callbacktextStatusThe parameter always returns "error", not a specific state text (such as "Bad Request"). Through the browser developer tools, you see that the response status line appears as "400 Bad Request", but in the codeBut it has always been "error". During further testing, it was found that the use of nativefetchAPIReturns an empty string. This makes it begin to study the changes in the HTTP protocol in different versions.

Problem analysis

Through analysis, it was found that the root cause of the problem lies in the design of the HTTP/2 and HTTP/3 protocols. The following are the key points:

1. Status line in HTTP/1.1

In HTTP/1.1, the status line consists of a status code and a reason phrase, for example:HTTP/1.1 400 Bad Request. The client can obtain the status code (400) and status text ("Bad Request") directly from the response.

HTTP/1.1 (RFC 7230, Section 3.1.2)：
The status line of HTTP/1.1 explicitly contains status codes and reason phrases. The original text is as follows:

status-line = HTTP-version SP status-code SP reason-phrase CRLF

in,status-codeIt is a three-digit status code.reason-phraseis the corresponding text description, such as "Bad Request". This means that in HTTP/1.1, the status text (such as "Bad Request") is part of the status line and must be sent by the server.

2. Changes in HTTP/2 and HTTP/3

In HTTP/2 and HTTP/3, the status line is simplified to contain only the status code, for example::status: 400. Cause phrases are no longer sent as part of the response. This is part of the protocol design designed to optimize performance and reduce redundant data.

HTTP/2 (RFC 7540, Section 8.1.2.4)：
HTTP/2 uses pseudo-header fields to represent status information and no longer contains reason phrases. The original text is as follows:

a single ":status" pseudo-header field is defined that carries the HTTP status code field (see [RFC7231], Section 6).
HTTP/2 does not define a way to carry the version or reason phrase that is included in an HTTP/1.1 status line.

In HTTP/2,:statusThe pseudo-head only carries the status code (such as 400) and does not define any fields for transferring the reason phrase. This suggests that the HTTP/2 protocol explicitly removes the design of the reason phrase.

HTTP/3 (RFC 9114, Section 4.1.1)：
HTTP/3 continues the HTTP/2 design, using similar pseudo-header fields to represent status information. The original text is as follows:

a single ":status" pseudo-header field is defined that carries the HTTP status code;
HTTP/3 does not define a way to carry the version or reason phrase that is included in an HTTP/1.1 status line.

Through the comparison of RFC definitions above, you can clearly see the changes in the status line design of HTTP/2 and HTTP/3: from the status code of HTTP/1.1 plus the reason phrase, simplifying it to only transmitting the status code. This change is to optimize protocol performance while transferring responsibility for generating state text to the client.

The behavior of developers tools: The developer tools of browsers (such as Chrome) infer and display standard status text based on status codes (such as "Bad Request"), but this is only local rendering and the actual response does not contain this text.
Impact of client library：
jQuery's$.ajaxUnder HTTP/2 and HTTP/3, the status text cannot be retrieved.Returns "error" by default.
NativefetchAPIReturns an empty string, complies with the protocol specification.

3. Server-side observation

The test server runs on Kestrel in Core and supports HTTP/1.1, HTTP/2 and HTTP/3. Under HTTP/1.1, the status text returns normally; but under HTTP/2 and HTTP/3, the status text is always missing.

Experimental verification

To confirm this design difference, the protocol was forced to downgrade to HTTP/1.1 on the server side, and the status text "Bad Request" was found to be returned normally. The code example is as follows:

// Core Kestrel configuration
 (options =>
 {
     (8081, listenOptions =>
     {
          = .Http1;
     });
 });

Under HTTP/2 and HTTP/3, the status text is still missing, which verifies the difference in protocol design.

Design Intent

The design of HTTP/2 and HTTP/3 removal of reason phrases is not accidental, but based on the following considerations:

1. Performance optimization

The reason phrase is human-readable text and has no practical significance for machine processing. Removing it reduces the size of the response header, thereby reducing network transmission overhead. This is especially important in scenarios where high concurrency or bandwidth limitations are present.

2. Agreement modernization

Modern web applications rely more on automated processing, and clients can map to standard text or custom error messages based on status codes. Decoupling the protocol layer from human readability simplifies protocol design.

3. Binary protocol features

HTTP/2 and HTTP/3 use binary frame formats, and the status codes are easier to encode and compress as numeric fields. And the reason phrases are as variable-length text, which are not conducive to the optimization of binary protocols.

Solution

To handle error responses gracefully in HTTP/2 and HTTP/3 environments, here are a few practical methods:

1. Manually map status code to status text

Maintain a mapping table of status codes to standard status text on the client to ensure that friendly error messages can be displayed even if the server does not send status text. For example:

const httpStatusTexts = {
     200: 'OK',
     400: 'Bad Request',
     404: 'Not Found',
     500: 'Internal Server Error'
     // More status codes
 };

 const statusText = httpStatusTexts[] || 'Unknown Error';

2. Analyze the response body

The server should return a JSON object with details in the error response. The client can parse responseText or responseJSON for more context. For example:

let responseData = ;
if (!responseData && ) {
    try {
        responseData = ();
    } catch (e) {
        responseData = ;
    }
}
(`Error: ${} - ${}`);

3. Use the fetch API

If jQuery does not behave as expected, you can use the native fetch API instead and manually process the status text and response body:

fetch(apiUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: ({ url, referrer })
})
.then(response => {
    if (!) {
        return ().then(text => {
            const statusText = httpStatusTexts[] ||  || 'Unknown Error';
            throw new Error(`${} - ${statusText} - ${text}`);
        });
    }
    return ();
})
.catch(error => {
    ('Failed to submit data:', );
});

in conclusion

The design of not sending reason phrases in HTTP/2 and HTTP/3 is the result of performance optimization and protocol modernization. While this may cause inconvenience in debugging or traditional client code, it can be easily dealt with by manually mapping status codes and parsing the response body. This change reflects the evolutionary trend of web protocols from human-first to machine-first.

References

HTTP/1.1 Specification section-3.1.2
HTTP/2 Specification section-8.1.2.4
HTTP/3 Specification section-4.3.2
MDN Web Docs:

author

Grok 3 automatically generated based on research content