rest - Appropriate HTTP Status Code for POST to create resource exceeding the limit

Question

I have been playing with a REST API. I've found a bug, my POST request used to get response with HTTP-401 code. Even though, the resource was created. That's not how it should work. That made me think that this API was not the greatest API in the world.

Then I fixed my request, everything looked fine but then the REST API returned HTTP-400. The reason was "resource limit was exceeded".

And here comes my question: What is the correct HTTP Status Code to handle the situation? I mean, the client exceeded the limit of resources and still he sends the POST request. I believe HTTP-400 is for malformed request, but everything is properly formatted. Shouldn't we use some other code? If yes, which one? HTTP-429 Too Many Requests seems also bad, maybe HTTP-422 Unprocessable Entity?

Answer 1

What is the correct HTTP Status Code to handle the situation?

Status code, like request method, is deliberately coarse grained; we're not trying to be ultra precise in describing the problem, but to broadly describe the general category of the problem, so that generic clients (like browsers and caches) can do the right thing when that code is seen in the response (for example: throwing up a login dialog when observing a 401 Unauthorized)

There are a number of decision trees to help select the appropriate code; I think I see Michael Koprat's most often; these tend not to be comprehensive, but usually cover all of the codes defined by HTTP -- you could also mine the status code registry for other options.

Then I fixed my request, everything looked fine but then the REST API returned HTTP-400. The reason was "resource limit was exceeded".

"Resource limit" seems a bit ambiguous to me, as the intended meaning might be that the size of the resource is too big -- in other words, that the message-body/content-length is too large (413 Payload Too Large would seem appropriate); alternatively, it might be an attempt to communicate that a quota has been exceeded a la 508 Resource Limit is Reached.

4xx should indicate something that the client can fix - a problem with the request, rather than a problem on the host. So that might be a hint that the 413 meaning is the one that is intended.

But if in the case where there is a problem in the request, and none of the other status codes seems to be a match, 400 Bad Request is fine.

The fine grained explanation for what's going on should be represented in the message body, but that doesn't always happen.

Body was NOT too large, the same request executed after deleting one of the resources got a successful response (that's why I think HTTP-400 is incorrect).

Fascinating: 4xx Too Many Notes. I think you could make a case for 403 Forbidden and 405 Method Not Allowed, with a payload that describes the condition as temporary and suggests possible remedies.

And is it really a server's error? Not client's one?

For the most part, if the client can untangle things, then you should be using a member of the 4xx class of status codes.