3

I have a DELETE operation for a customer resource in a Web API. The URI will look like /customer/1000/. This operation will deactivate the customer internally by the system.

There are some cases the customer can't be cancelled due to he owns the business a payment.

In the case of successful cancel, the API return 200. What should the API return if the cancellation fails due to the pending payment? Can I return still 200 but a message object as the response with the error?

wonderful world
  • 10,969
  • 20
  • 97
  • 194

2 Answers2

13

If you cannot fulfill a request, it is imperative to return an appropriate status code. Since the client is at fault and can correct the state, the 4xx-class of codes seems fitting. From RFC 7231, section 6.5:

The 4xx (Client Error) class of status code indicates that the client seems to have erred.

The way I see it, there are three applicable codes:

400 / Bad Request

400 is a bit broad in definition and has been turned (at least that is my impression) into a catch-all status. So if you are unsure, 400 is almost always a safe bet.

403 / Forbidden

This status is often linked to the HTTP authentication framework. Unjustly so. From the RFC:

The 403 (Forbidden) status code indicates that the server understood the request but refuses to authorize it.

[...] a request might be forbidden for reasons unrelated to the credentials.

In this scenario this would be a bit of a stretch, but not entirely unreasonable.

409 / Conflict

The 409 (Conflict) status code indicates that the request could not be completed due to a conflict with the current state of the target resource. This code is used in situations where the user might be able to resolve the conflict and resubmit the request.

IMHO this is the one to pick. The RFC is mentioning the PUT verb but avoids strictly linking 409 with it.

Community
  • 1
  • 1
DaSourcerer
  • 6,288
  • 5
  • 32
  • 55
  • `409` is for HTTP only, for instance if you `PUT` with outdated `ETag`. I'd go with `422` that is from WebDAV RFC. – gavenkoa Mar 15 '20 at 20:57
  • @gavenkoa That is a *very* WebDAV-centric interpretation. 422 implies a semantic error with the requests and neglects the state of the resource. Here, the request were correct and serviceable if the resource was in another state. I would still stand by 409. – DaSourcerer May 28 '20 at 10:11
  • Another thing to consider is logging setup & frameworks. Frameworks may occupy 409 and you won't have distinctive business logic error code (( And we sholdn't forget that you can use 4xx freely according to RFC! Codes are extensible by standard! I'd focus on coherant API & and logging/alerting requirements then ultimately stick to 409 or 422 or other 4xx... – gavenkoa May 28 '20 at 23:20
  • Main point regarding 409 - it's for Etag & versioning of resources, managing conflicts (has well defined purpose). So if you follow REST HTTP based API design to the end words of standarts, it is inapropriate. Although real world APIs are not that eager to follow umbigious standards and come up with own creative conventions. – gavenkoa May 28 '20 at 23:28
  • No, it is not. 409 does not require an ETag missmatch or a precondition (i.e. `If-*`) violation. I can see why you think 422 were more apropriate, but please consult [RFC 4918, sec. 11.2](https://tools.ietf.org/html/rfc4918#section-11.2) again. – DaSourcerer May 28 '20 at 23:50
-1

Technically, yes. See this post for really good advice on web api error messages Best practice to return errors in ASP.NET Web API.

I tend to avoid returning anything 2XX for an unsuccessful operation, but that is personal preference as there a no definite rules for such things. I think that may confuse the end user in some cases as they have been unsuccessful. In the same way I avoid 5XX as that gives the impression that there's an internal error or perhaps they should resubmit.

There's a forum post here that is relevant and makes some good points: https://groups.google.com/forum/#!topic/api-craft/_dfnBKImNCI The suggestion in the post above to use a 403 with a custom error code and message is what I would suggest in this case as it seems to be the closest fit.

Hope that helps :)

Community
  • 1
  • 1
scar
  • 62
  • 4
  • 4
    "no definite rules for such things" I [beg to differ](https://tools.ietf.org/html/rfc7231#section-6)? – DaSourcerer Feb 16 '17 at 00:43
  • @DaSourcerer I meant that there's no way to prescribe a code for every individual situation, sometimes you could have several acceptable options. But that article does summarise the 'families' of response code very well :) – scar Feb 16 '17 at 02:05
  • "Article?" I take it you are new to webdev? – DaSourcerer Feb 16 '17 at 02:14
  • Article as in 'article 6', could say section I guess? I am aware of the standard, not thaaat new to dev :P Though if I'm perfectly honest it's not something I reference directly on a regular basis. Anyways, this does feel a little off topic ;) – scar Feb 16 '17 at 02:24
  • Ah, my apologies then. It sounded to me like you downgraded a RFC to a mere opinion piece there. – DaSourcerer Feb 16 '17 at 02:30