HTTP status code for limited collection?

Question

I have a restful service where one of the collections is limited (for UX reasons). In this case it has a cap of 25 items. If that is exceeded resources must be deleted before more can be added. As an example if a client submits:

POST http://somesite.com/api/v2/stuff
{"cool":"stuff"}

and there are < 25 things in stuff:

200 OK

if > 25 things in stuff:

???

DELETE http://somesite.com/api/v2/stuff/:id

POST http://somesite.com/api/v2/stuff
{"cool":"stuff"}

200 OK

What is the best code for this? Straight 400? 409 CONFLICT? 429? None seem quite right..

Answer 1

Use 409. From httpbis section 7.5.8:

"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 payload SHOULD include enough information for the user to recognize the source of the conflict."

In your case, the resource is the one identified by http://somesite.com/api/v2/stuff, and the POST request cannot be completed due to a conflict with its current state (which is that it is already maxed out). In your response, give the user enough info (preferably links) to delete one of the existing members, up the limit, or take some other action. Then they can resubmit the original request.