Question

Assume that I have a resource (e.g: /api/shipments/100) which supports HTTP DELETE method. As you can understand from the URI itself, if a DELETE request is made against this URI, this resource will be removed.

In my current scenario, the DELETE request can only be performed successfully if a certain condition is met as below:

• If the shipment state is not set to InTransit or Delivered.

If there is a DELETE request against that URI and the above condition is not met, which HTTP status code would be more proper to return in that case? I have thought about the below ones but couldn’t decide which one is more semantic:

• 405 Method Not Allowed
• 403 Forbidden
• 409 Conflict

Answer 1

I would go with 409: Conflict, because what you have is a violation of resource state.

405: Method Not Allowed would also work. If you’d want to use a 405, you’d have to send an Allow header to indicate the supported methods, and the supported methods would vary depeding on the resource’s state. In my opinion, this response code fits well for read-only resources, resources that can’t be deleted etc. but Darrel‘s comments to this post are valid. The spec is ambiguous:

The method specified in the Request-Line is not allowed for the
resource identified by the Request-URI. The response MUST include an
Allow header containing a list of valid methods for the requested
resource.

In either case, you should provide information in the response body for the client to understand the source of the error.

---

Regarding the other two methods mentioned:

403: Forbidden should be used when you don’t have the appropriate privileges to modify the resource, i.e. if you have to be an admin to delete that resource and you’re not.

412: Precondition Failed is mostly used for conditional requests where the preconditions are specified explicitly in the request headers. For example, you can have conditional PUT requests that should be carried out only when the If-Match header is valid. If you don’t specify anything in the request headers, I’d still choose 409 over 412. Here’s the spec for 412:

The precondition given in one or more of the request-header fields
evaluated to false when it was tested on the server. This response
code allows the client to place preconditions on the current resource
metainformation (header field data) and thus prevent the requested
method from being applied to a resource other than the one intended.