REST API error code 500 handling

Question

We are building a new REST API.

I was arguing that error code 500 (Internal Server Error) should never be returned.

Now, of course if you know the client's params are wrong or something you have everything under control and can return some appropriate error code (e.g. 422).

So if an unexpected error occurs the server could:

1. NOT catch unexpected errors so that 500 bubbles up to the client
2. Catch any unexpected errors and return some error code signaling an "unexpected situation" (honestly I couldn't find any such error code!)

Are there other options?

Solution 1

It is a server error, not a client error. If server errors weren't to be returned to the client, there wouldn't have been created an entire status code class for them (i.e. 5xx).

You can't hide the fact that you either made a programming error or some service you rely on is unavailable, and that certainly isn't the client's fault. Returning any other range of code in those cases than the 5xx series would make no sense.

RFC 7231 mentions in section 6.6. Server Error 5xx:

The 5xx (Server Error) class of status code indicates that the server is aware that it has erred or is incapable of performing the requested method.

This is exactly the case. There's nothing "internal" about the code "500 Internal Server Error" in the sense that it shouldn't be exposed to the client.

Solution 2

The real question is why does it generate a 500 error. If it is related to any input parameters, then I would argue that it should be handled internally and returned as a 400 series error. Generally a 400, 404 or 406 would be appropriate to reflect bad input since the general convention is that a RESTful resource is uniquely identified by the URL and a URL that cannot generate a valid response is a bad request (400) or similar.

If the error is caused by anything other than the inputs explicitly or implicitly supplied by the request, then I would say a 500 error is likely appropriate. So a failed database connection or other unpredictable error is accurately represented by a 500 series error.

Solution 3

You suggested "Catching any unexpected errors and return some error code signaling "unexpected situation" " but couldn't find an appropriate error code.

Guess what: That's what 5xx is there for.

Solution 4

Generally speaking, 5xx response codes indicate non-programmatic failures, such as a database connection failure, or some other system/library dependency failure. In many cases, it is expected that the client can re-submit the same request in the future and expect it to be successful.

Yes, some web-frameworks will respond with 5xx codes, but those are typically the result of defects in the code and the framework is too abstract to know what happened, so it defaults to this type of response; that example, however, doesn't mean that we should be in the habit of returning 5xx codes as the result of programmatic behavior that is unrelated to out of process systems. There are many, well defined response codes that are more suitable than the 5xx codes. Being unable to parse/validate a given input is not a 5xx response because the code can accommodate a more suitable response that won't leave the client thinking that they can resubmit the same request, when in fact, they can not.

To be clear, if the error encountered by the server was due to CLIENT input, then this is clearly a CLIENT error and should be handled with a 4xx response code. The expectation is that the client will correct the error in their request and resubmit.

It is completely acceptable, however, to catch any out of process errors and interpret them as a 5xx response, but be aware that you should also include further information in the response to indicate exactly what failed; and even better if you can include SLA times to address.

I don't think it's a good practice to interpret, "an unexpected error" as a 5xx error because bugs happen.

It is a common alert monitor to begin alerting on 5xx types of errors because these typically indicate failed systems, rather than failed code. So, code accordingly!

View more solutions

Comments

[H.M.Mubashir]

Understood and I agree. I was trying to find out if a difference can be made if the developer is handling all cases or not. Actually it makes no sense to think that way. There's no difference in a developer catching an unexpected error and returning 500 or not catching it - the test failed and that's the important issue I guess.

[CodeCaster]

If you want to differ between a handled and unhandled server exception, you may do that using logging (at the server side) or in the request body (so the client, in this case your test).

[CodeCaster]

"If it is related to any input parameters [..]: 400" - what if the error is caused by an uncaught null dereference exception on a request variable? It is caused by a programming error (server), triggered by the request (client). And what if the request variable isn't required by the server logic, but the programmer did assume (hence not check) it? The point is: most web frameworks return 5xx codes upon detecting abnormal termination of the server software. This framework can't differentiate between a client and server error as such.

[tokkov]

True, but the question was framed in the context of testing a presumably new service and soliciting feedback on how the situation should ultimately be handled. If I were testing new services and generated a 500 through edge case input test cases, I would flag that as a failed test and work with the developer to handle the test scenario either with a more descriptive error (400, 404, etc) or a properly serviced request (200). There are truly unforeseeable sources of 500 errors, but you can/should defend against them as much as possible even if that is simply giving a more informative error.

[Shehan Thamel]

helpful clarification. But can this 500 status code be returned from server because of any formatting issues in the request body?