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 Lockedas 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.