REST API & HTTP Status Code

Question

I have a bunch of PUT operations which execute actions on the input resource. Let's make an example: I have a payment operation in my API which state that a credit card must be charged by a specific Amount. In my code I first verify if there is sufficient credit on the card and then execute the operation. If there is'nt sufficient amount I simply return 400 but I am not sure it is correct.

Which is the correct HTTP Status Code in cases like this?

I can, of course send a response with HTTP 200 and attach a payload with further details explaining the error. I can also send back an HTTP 400 Bad Request or even better an HTTP 412 Precondition Failed.

Which is the correct code to send in the response in scenario like this where the validation failed? Is there any resource that I can read to understand the rationale behind HTTP Status Codes and HTTP Verbs?

Robert Harvey · Accepted Answer · 2015-03-26T16:39:22.867

3

Use 422 Unprocessable Entity.

The 422 status code means the server understands the content type of the request entity (hence a 415 Unsupported Media Type status code is inappropriate), and the syntax of the request entity is correct (thus a 400 Bad Request status code is inappropriate) but was unable to process the contained instructions.

Failing that, simply use 400 for any error having to do with your business domain. As of June 2004, the description for error 400 was amended to read:

The server cannot or will not process the request due to something that is perceived to be a client error

edited Mar 26 '15 at 16:39

answered Mar 26 '15 at 14:37

Robert Harvey

178,213
47
333
501

Thanks for your answer. However, while your answer make sense to me, I can't simply find a correspondant enum value in the `System.Net.HttpStatusCode` enumeration. In facts this enumeration jumps from 417 to 426. Is that correct? – Lorenzo Mar 26 '15 at 16:28
1

It's more important to provide a meaningful payload (and document what happens when an error occurs) than it is to use the "correct" HTTP error code. See also http://stackoverflow.com/a/3290198/102937, which says that the description for error 400 changed as of June 2004, making it more suitable for your error condition. – Robert Harvey Mar 26 '15 at 16:38

score 3 · Answer 2 · edited Mar 26 '15 at 15:02

If the operation failed because of data sent by the user (it seems to be the case), you should use status codes 400 (general) or 422 (more precise but coming from the WebDAV spec). You can return back additional hints about the error within the payload (the structure is up to you) like:

{
    error: {
       "field": "amount",
       "message": "The amount isn't correct - Sufficient credit."
    }
}

I think that code 412 doesn't apply here since it must be returned when your server doesn't meet a condition specified by the client (see headers If-* like If-Match, If-Modified-Since, ...).

Hope it helps you, Thierry

score 1 · Answer 3 · edited Apr 22 '16 at 17:37

IMO: I would stick with 200 and then parse out the response and deal with that. HTTP status codes are protocol status code, not something that you should use for dealing with application logic.

{
    "error": {
       "field": "amount",
       "message": "The amount isn't correct - Sufficient credit."
    }
}

In case of the above code, the service call worked fine warranting a return code 200. However, you application logic now needs to deal with the error reported.

If we are using a HTTP status code to indicate error, we will start to get flagged in our logs etc. even though there was no technical error.

REST API & HTTP Status Code

3 Answers3