针对业务异常的REST API设计

Question

There is a debate in our team regarding how the REST API should behave when the server encounters a business exception (maybe a validation or some other business related exception).

Part of the team claims that the server should send 200 as status every time, with a flag and code on the response. As far as I know, this approach breaks the HTTP status codes principle and the Richardson Maturity Model .

The other part of the team wants to map business exceptions to HTTP status codes. Is this approach following the REST principles or business exceptions are not covered there?

I'm just curious to hear other opinions regarding this debate.

Answer 1

We solved the issue in our team by "enjoying" both worlds:

We map the business exceptions to the closest HTTP code. For example if a user asks for an entity that is not found, we give out 404.

In the response we give an error JSON that holds all the business related information similar to this one:

[
    {
        "code": 4004, // This is our application specific code in thousands instead of hundreds
        "message": "entity <bla bla> not found",
        "stack": ... // The stack trace for debugging
        "headers": ... // The request headers also for debugging
    },
    {
        ... // Another error JSON here
    }
]

Note that it is an array cause sometimes we find more than 1 error in the input validation logic.

Answer 2

REST supports the usage of standards over custom solutions. So if you use HTTP as the underlying protocol, then I think you should map your error types to HTTP status headers instead of developing a custom solution which does not meat with the HTTP standard. This is part of the uniform interface / self descriptive message constraint. The text does not mention the HTTP status header, but the HTTP methods and other headers are part of it as examples of the uniform interface which applies standards, so I think the intent is very clear...

Ofc. it is allowed to send a more specific message body about the error along with the proper status header.