Recommended HTTP status code for "plan limit exceeded" response

Question

I'm designing a REST API for a project where users are always on one of several "plans" - each plan defines some resource limits, such as the max number of users an account may have or the max number of data they may upload. Once one of these limits is reached, users can upgrade their plans (essentially pay up) to get more resources.

I want to return a special status code indicating a situation where the action cannot be performed due to account resource limits, and upgrading the plan will resolve this - for example if a user uses 100% of their storage capacity and try to upload an additional file, they will get this response.

The candidates are, IMHO:

• 403 Forbidden - however, I would like to distinguish between this case and other cases where the user simply lacks the permission to perform this action.

• 401 Unauthorized - not a good idea, we're using this for authentication related problems.

• 402 Payment Required - makes kind of sense but I'm worried about using a non-standard yet reserved status code

• Something even less standard like 423 Locked as its unlikely we'll use it for anything else in the future

Another option is to go with something very standard such as 403 but indicate the specifics of the error in the response body.

I'm wondering which approach you believe would (a) work best in the long run and (b) would stick more nicely to RESTful principles.

Answer 1

I think 403 is the only reasonable response, though 405 Method Not Allowed or 409 Conflict might be acceptable, I don't think either are as good as 403 which states:

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. If the request method was not HEAD and the server wishes to make public why the request has not been fulfilled, it SHOULD describe the reason for the refusal in the entity

If you return a 403 error, it'll include some information on why the resource was denied - invalid permission is only the most common case, exceeded limits isn't much different - you don't have permission because your limit was exceeded.

Answer 2

I believe 403 is wrong, because 403 is for situations where you aren't getting access to the resource, and there is no way whatsoever to get access. For your customers, there is obviously a way to get access: Pay up.

401 is truly wrong, because not only are you using it for authentication, but that is what it is there for.

Since you are writing an API, I assume that someone else will have to write code that uses the API, and that person needs to read your API spec. You might go with 429 "Too many requests". It is usually intended for rate limiting (where a client can make 100 requests per day, for example), but does reasonably apply to your situation. 402 (Payment required) would also be acceptable, I think. Depends on what tools you expect people to use to use your API. 429 has the risk that a clever tool tries to send fewer requests per minute/hour/day and never succeeds.

BTW according https://www.rfc-editor.org/rfc/rfc6585 the 429 error should also contain an html message describing the nature of the problem, so there's a good chance that the user is actually told what the problem is, if you supply that information in your response.

Answer 3

WebDAV uses HTTP 507 Insufficient Storage for this and includes an additional error code for quota exceeded in the request body, to distinguish it from other kinds of storage limitations.