Recommended HTTP Status Code for Plan Limit Exceeded Response

api-designhttprest

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.

Best Answer

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.

429 Too Many Requests

The user has sent too many requests in a given amount of time. Intended for use with rate limiting schemes. This code has been accepted in RFC 6585 Additional HTTP Status Codes.

   The 429 status code indicates that the user has sent too many
   requests in a given amount of time ("rate limiting").

   The response representations SHOULD include details explaining the
   condition, and MAY include a Retry-After header indicating how long
   to wait before making a new request...

   Note that this specification does not define how the origin server
   identifies the user, nor how it counts requests.  For example, an
   origin server that is limiting request rates can do so based upon
   counts of requests on a per-resource basis, across the entire server,
   or even among a set of servers.  Likewise, it might identify the user
   by its authentication credentials, or a stateful cookie.

   Responses with the 429 status code MUST NOT be stored by a cache...

How to Handle Business Rules with a REST API

You want to you 403 Forbidden. From the HTTP specs

403 Forbidden: The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated.

You shouldn't use 409, it implies that the client might be able to resolve the conflict, which in the case of over booking the client can't do as the conflict rules are server side.

Remember in the context of HTTP status codes "conflict" means a conflict in the state of the resource (in this case the book time slot), ~~for example it expects time in one format and you sent it in the wrong format~~ [bad example, better one would be two clients update a resource at the same time and the server cannot figure out which update to save, like on a version controlled system]. The resource is a time slot, if you change to a different time slot you have created a different resource, not resolved a conflict with this resource.

409 Conflict: The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request.

The server should return 403 Forbidden with an explanation that it is refusing to save the state because that time slot is already full. Nothing the client can do in altering the state of the resource can change that. The client should not re-submit. They must instead create a new time slot instead (you could return the closest free slot as a suggestion).

Best Answer

Related Solutions

HTTP REST Status Code – Suggested Code for ‘Request Limit Reached’

429 Too Many Requests

How to Handle Business Rules with a REST API

Related Topic