I'm working on a project where I'm building the frontend and someone else is building an API. I was proposing the following structure for all requests, sent as JSON:

{
  "success": true, // true/false
  "message": null, // a string if success==false indicating the error
  "data": {} // The actual data in the response
}

They are more interested in making the API more RESTful, and instead of a "message" field they are proposing sending a message back in the status code message, in the HTTP headers, such as:

HTTP/1.1 401 Authentication Failed for [email protected]. Please log in again.

and the frontend would display "Authentication Failed for [email protected]. Please log in again." in a popup or something.

I'm worried about length restrictions, but I couldn't find anything indicating no maximum length. Should we ensure we keep those messages to a minimum length? Is there a good reason to not do this, and instead send it back as content (JSON or plain text)?

I'm working on a project where I'm building the frontend and someone else is building an API. I was proposing the following structure for all requests, sent as JSON:

{
  "success": true, // true/false
  "message": null, // a string if success==false indicating the error
  "data": {} // The actual data in the response
}

They are more interested in making the API more RESTful, and instead of a "message" field they are proposing sending a message back in the status code message, in the HTTP headers, such as:

HTTP/1.1 401 Authentication Failed for [email protected]. Please log in again.

and the frontend would display "Authentication Failed for [email protected]. Please log in again." in a popup or something.

I'm worried about length restrictions, but I couldn't find anything indicating no maximum length. Should we ensure we keep those messages to a minimum length? Is there a good reason to not do this, and instead send it back as content (JSON or plain text)?

• javascript
• json
• rest
• http-status-codes

• In my tests with IIS Express and Google Chrome, I got ERR_CONNECTION_RESET errors when having a too long error message and/or having line breaks contained. – Uwe Keim Commented Jan 30, 2018 at 6:37

2 Answers 2

A little testing will go a long way, but you should be okay to do this and in fact the RFC says specifically:

The reason phrases listed here are only remendations -- they MAY be replaced by local equivalents without affecting the protocol.

The only possible concern you may have is header size (some servers may have limitations, but I think they are all relatively large) and how some older browsers may react to this. Frankly I think it makes more sense to use the response body since it's easier to interpret and clear, but there shouldn't be anything wrong with your approach.

I want to add, although there might be no limit in the specification, there is a real chance of implementations to truncate the status message, as I discovered, when I was trying something similar as the OP with Jetty 9.4.14 .

It took me some time to find the reason for the truncated message - there is a hard coded, not configurable limit of 1024 characters [see method getReasonBytes(String)].

(could not post this as ment due to lack of reputation)