In the JSend specification, what is the difference between a fail and an error?

Question

According to https://labs.omniti.com/labs/jsend,

• Fail: When an API call is rejected due to invalid data or call conditions
• Error: When an API call fails due to an error on the server

Can this be interpreted as 4xx errors (such as a 404) should always return a Fail, but 5xx errors always correspond to a Error?

Aliber

Later on it says "it is advised that server-side developers use both: provide a JSend response body, and whatever HTTP header(s) are most appropriate to the corresponding body."...so if you think those errors are most appropriate to those situations (and broadly I'd agree with you) then go ahead. – Murk

Answer 1

This is a great question and I'll answer it with a concrete example from my own experience. In an API for one of my projects, I allow the upload of an Excel spreadsheet, which is processed and the resulting JSON is stored on the server.

If there is an error saving the data to disk, then I would respond with a JSend "error" along with the appropriate error message since the data should have been able to be saved.

If, on the other hand, the data in one of the rows is not valid (maybe an incorrect data type or a range error), then I know the exact row (or rows) of the spreadsheet that were incorrect. In this case, a "fail" response is appropriate as the data property of the JSend response will contain a list of all rows (the row number and the error message) for each unprocessable row.

In the case of an "error" response, I wouldn't have that ability as I would be limited to a single message property. But with the "fail" response, I have the data property available where I can respond with a fine-grained list of issues.

So, while there was no error, the data itself was not correct and the user should go back and look at their spreadsheet and fix the issues identified by the data property in the "fail" response.

Thinking of this in terms of HTTP errors, although an interesting exercise, doesn't always result in an exact mapping (4xx = fail, 5xx = error). It's more about what you want to communicate to the client: something bad happened that shouldn't have happened ("error") or the server is working fine but your data isn't quite up to standards ("fail").

Finally, whether you want to also use HTTP errors is entirely up to you. You could always respond with a 200 and let JSend do the talking. But that's a slightly different (and somewhat religious) discussion. :-)

I hope that helps.

Whiteeye

I find this answer confusing: You say: "Thinking of this in terms of HTTP errors, although an interesting exercise, doesn't always result in an exact mapping (4xx = fail, 5xx = error)." In your example you respond fail when there is a problem with the spreadsheet and error if e.g. it can't be saved to disk even if ok. Isn't that exactly 4xx: "Client_errors" vs. 5xx: "Server errors"? Do you have an example where fail should be HTTP error code 5xx or where error should be 4xx? – Nefertiti

Peter, you make a valid point. Where I struggle (almost a year after I wrote this), is with the JSend specification making fail being "bad-data oriented" and the message key is neither required nor optional. I can imagine a PUT request with a timestamp inconsistency between the client and the server (based on HTTP headers, and not on client data) resulting in a 409 (Conflict) response. Clearly, there is nothing wrong with the data per se and a JSend error response with a code of 409 and a message of "Entity on server is more recent than request data." is entirely appropriate. – Whiteeye

In my personal opinion using JSend for a REST API, the root problem is JSend's dismissal of HTTP headers as an integral part of a REST API. JSend's status field is redundant, as this information is already in in the Status HTTP Header (they're even called the same thing). "The spec is meant to be as small, constrained, and generally-applicable as possible. As such, it has to be somewhat self-contained." - But REST should embrace HTTP headers and verbs, not pretend they don't exist. – Nefertiti

Indeed. These days, I find myself using HTTP status codes and a simple object with a message property on error. This way, there is zero friction with axios or related libraries. JSend seems to try to solve a problem that really was never there. – Whiteeye

I know this is a bit strange but if you think of it like that maybe it will be understandable (if you (Client) Fail to give me the right data I will give you (Server) an Error ) Servers always give an error, Client always Fail to give right data. Right @FrankHellwig – Maecenas

@Maecenas Exactly. I like your logic. By that thinking, even a 404 is technically a "fail" vs an "error" as the client failed to provide a valid URL. So yes, you (the client) failed to provide a valid location. Cool. – Whiteeye