By alexn

2010-07-20 13:03:07 8 Comments

I'm building an application with a REST-based API and have come to the point where i'm specifying status codes for each requests.

What status code should i send for requests failing validation or where a request is trying to add a duplicate in my database?

I've looked through but none of them seems right.

Is there a common practice when sending status codes?


@Phil Parker 2014-10-16 23:05:13

A duplicate in the database should be a 409 CONFLICT.

I recommend using 422 UNPROCESSABLE ENTITY for validation errors.

I give a longer explanation of 4xx codes here.

@deamon 2010-07-20 13:05:04

For input validation failure: 400 Bad Request + your optional description. This is suggested in the book "RESTful Web Services". For double submit: 409 Conflict

Update June 2014

The relevant specification used to be RFC2616, which gave the use of 400 (Bad Request) rather narrowly as

The request could not be understood by the server due to malformed syntax

So it might have been argued that it was inappropriate for semantic errors. But not any more; since June 2014 the relevant standard RFC 7231, which supersedes the previous RFC2616, gives the use of 400 (Bad Request) more broadly as

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

@deamon 2010-07-20 13:22:11

Yes, the request body is part of the syntax.

@alexn 2010-07-20 13:24:33

Yeah, 400 Bad Request seems to be the closest option.

@alexn 2010-07-20 13:43:54

I will go with 400 Bad Request and 409 Conflict until i find something that fits better.

@Darrel Miller 2010-07-20 19:38:11

Bad request is definitely the most common response to this kind of issue. The only other alternative is 422 Unprocessable Entity. It actually comes from WebDav but it is perfectly valid to reuse any status code that has been registered with IANA.

@Josh Noe 2013-02-19 18:59:00

So how do you differentiate between malformed data that the server can't even parse, and a validation error? A client would handle these two responses completely differently. For validation, they'd likely display the errors to the user. For truly "malformed data", they would log the error so the the bug in the method that generates the request could be fixed.

@Dima Tisnek 2014-09-23 12:22:06

I disagree with your interpretation of RFC7231, although it states something perceived to be a client error, all the examples given in this paragraph are violations of HTTP protocol, not logical errors: syntax, framing, routing. Thus, I consider that HTTP spec does not allow 400 for failed validation on application level.

@java_geek 2014-10-07 09:59:52

why not use a 422 - Unprocessable entity? Seems more logical to me

@Sinaesthetic 2015-11-20 16:12:50

I agree that 409 is appropriate for dupes, but sometimes dupes are a side effects of an error case. For example, a mobile client may timeout during submission and never receive 201 Created with a payload containing an ID that they need. I submit that when appropriate (or even possible), an alternative would be a 303, redirecting to the original that was created before the timeout.

@Pocketsand 2016-05-19 14:05:54

I have read that custom status text is deprecated in HTTP/2, can't find the reference unfortunately.

@Worthy7 2016-08-31 10:22:54

Just my 2 cents, I read somewhere that sometimes webservers/browsers SOMETIMES round the 4xx part of codes down to 00.

@Marcodor 2017-09-23 12:42:37


Ugh... (309, 400, 403, 409, 415, 422)... a lot of answers trying to guess, argue and standardize what is the best return code for a successful HTTP request but a failed REST call.

It is wrong to mix HTTP status codes and REST status codes.

However, I saw many implementations mixing them, and many developers may not agree with me.

HTTP return codes are related to the HTTP Request itself. A REST call is done using a Hypertext Transfer Protocol request and it works at a lower level than invoked REST method itself. REST is a concept/approach, and its output is a business/logical result, while HTTP result code is a transport one.

For example, returning "404 Not found" when you call /users/ is confuse, because it may mean:

  • URI is wrong (HTTP)
  • No users are found (REST)

"403 Forbidden/Access Denied" may mean:

  • Special permission needed. Browsers can handle it by asking the user/password. (HTTP)
  • Wrong access permissions configured on the server. (HTTP)
  • You need to be authenticated (REST)

And the list may continue with '500 Server error" (an Apache/Nginx HTTP thrown error or a business constraint error in REST) or other HTTP errors etc...

From the code, it's hard to understand what was the failure reason, a HTTP (transport) failure or a REST (logical) failure.

If the HTTP request physically was performed successfully it should always return 200 code, regardless is the record(s) found or not. Because URI resource is found and was handled by the HTTP server. Yes, it may return an empty set. Is it possible to receive an empty web-page with 200 as HTTP result, right?

Instead of this you may return 200 HTTP code with some options:

  • "error" object in JSON result if something goes wrong
  • Empty JSON array/object if no record found
  • A bool result/success flag in combination with previous options for a better handling.

Also, some internet providers may intercept your requests and return you a 404 HTTP code. This does not means that your data are not found, but it's something wrong at transport level.

From Wiki:

In July 2004, the UK telecom provider BT Group deployed the Cleanfeed content blocking system, which returns a 404 error to any request for content identified as potentially illegal by the Internet Watch Foundation. Other ISPs return a HTTP 403 "forbidden" error in the same circumstances. The practice of employing fake 404 errors as a means to conceal censorship has also been reported in Thailand and Tunisia. In Tunisia, where censorship was severe before the 2011 revolution, people became aware of the nature of the fake 404 errors and created an imaginary character named "Ammar 404" who represents "the invisible censor".

Why not simply answer with something like this?

  "result": false,
  "error": {"code": 102, "message": "Validation failed: Wrong NAME."}

Google always returns 200 as status code in their Geocoding API, even if the request logically fails:

Facebook always return 200 for successful HTTP requests, even if REST request fails:

It's simple, HTTP status codes are for HTTP requests. REST API is Your, define Your status codes.

@szczepanpp 2017-12-06 11:41:39

Actually, using HTTP status codes for REST is even more confusing down the road: 1) you see 4xx in your developer's toolbox and you can't say by just glancing at it whether server returned some sensible value or failed to process your request at all and then 2) all your error/exception/catch handlers should check what server returned as a response (mostly they don't since you'd have to do it on every service call) and many times 3) you get the same payload (type) on both success and error path leading to complicated/duplicated code... Very confusing indeed.

@Kevin Hooke 2018-01-08 02:37:07

This answer confuses the original semantics of the HTTP protocol vs how REST over HTTP as an architectural style re-purposes HTTP to implement web service APIs. As an architectural style, REST is not a standard to be rigorously followed, it is a suggested approach. Using a 200 response for a validation failure is not right or wrong, however it is confusing to your clients to respond that the request succeeded, but actually failed due to a validation failure, an important detail that is obscured within the body of the response, the semantics of which the client has to parse to understand.

@Marcodor 2018-01-09 09:37:54

@KevinHooke, this answer argue why using HTTP return codes is a bad idea for REST status calls.

@Kevin Hooke 2018-01-09 16:03:16

@Marcodor if your API call fails but you return 200 indicating success, how is this a good idea? it's unclear and confusing to consumers of your API.

@Neil Laslett 2018-10-01 15:08:57

Correct for many reasons, not just the separation of HTTP vs REST errors. REST validation often requires more nuance. For example, record accepted but flagged as a duplicate vs. rejected for a unique index violation. You also want a consistent return model. The .NET BadRequest() method has its own return model that will differ from your regular return model. That's a nightmare to parse. @KevinHooke, returning HTTP 200 for a REST validation error is like saying, "I received your message, the answer is no, and here's why." Returning HTTP 400 says, "I don't know what you're talking about."

@Jeryl Cook 2018-12-18 11:47:48

the "because google does it , it must be right" argument is crazy to me..its ok to challenge something google has implemented kids. Returning HTTP 200 for an unsuccessful rest call confuses the caller of the API it should be 4xx and one can include a pretty JSON/XML in the body...lets stop the insanity together.

@Marcodor 2018-12-20 19:04:00

@JerylCook, last phase with Google I added after one year of original answer, when found accidentally how does Google, during one integration. And I thought: Hey Google read this answer, they think I am right and they copied me. I should ask for royalties. :) I think I argued enough about caller confusion... Http status codes are for Http requests. Rest codes: define yourself. Http codes will not be enough for a complex API design. Lets eat the soup with a spoon, not with a fork.

@Marcodor 2018-12-20 19:11:23

Oh h..t, just checked how Facebook do it, crazy... they too copied me )…

@Pavlo 2019-01-11 16:54:25

What would you say if some of Google projects resources returns 2xx but others 4xx? Did you checked all of them? Google is quite large and they fail quite often. They have a lot of nice stuff too. So when you mention some company it is not an argument, but rather an illustration. The idea you proposed is new for me, and have some sense, but as REST is not a standard how to compare it with HTTP?

@Bernoulli IT 2019-11-13 07:32:58

The explanation makes a lot of sense to me and I will implement it like so. But I will rename the "result" property to "success" because "result=false" is confusing and not telling me anything. There is a result, but it wasn't successful for some reason is more appropriate.

@Marcodor 2019-11-13 08:03:38

@BernoulliIT, indeed, many implementations uses "success" property. We also did it in a lot of projects, as front-end like ExtJS impose it.

@Brian 2019-11-14 05:39:04

Using the HTTP response codes in REST is part of "level 2" of the Richardson maturity model. see (for example)‌​2: "The important part of this response is the use of an HTTP response code to indicate something has gone wrong". REST does often require more nuance, but the HTTP verbs and status codes do exist, and are worth using as correctly as possible.

@Julian Reschke 2010-07-20 14:56:26

I recommend status code 422, "Unprocessable Entity".

11.2. 422 Unprocessable Entity

The 422 (Unprocessable Entity) 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. For example, this error condition may occur if an XML request body contains well-formed (i.e., syntactically correct), but semantically erroneous, XML instructions.

@Julian Reschke 2010-07-20 15:16:09

Of course it is an HTTP status code, see There are more status codes than those defined in RFC 2616.

@Piskvor left the building 2010-07-20 15:24:00

@deamon: Speaking of non-codes, the Wikipedia page you linked to (somewhere in this question), notes several sub-statuses (which are not even syntactically valid HTTP status codes - "The Status-Code element is a 3-digit integer result code") invented by the IIS server team ("403.4 - SSL required"). Trying to eat your cake and have it, too?

@deamon 2010-07-20 15:28:05

WebDAV is a HTTP extension. "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)" So, status code 422 is not a http status code, but a status code of an extions of http.

@Julian Reschke 2010-07-20 15:32:17

deamon, that doesn't make sense. HTTP defines how to define new codes, and that's what WebDAV is doing. There's a status code registry for a reason.

@Julian Reschke 2010-07-20 15:53:21

Piskvor, that's actually questionable :-). It probably wouldn't happen under the registration procedure defined in the current draft.

@Julian Reschke 2010-07-24 07:45:13

Piskvor, Oh, it's NOT in. Good. :-)

@Josh Noe 2013-02-19 19:06:52

This is what Twitter uses now. Not saying they're the law, but worth noting.

@Steve Kallestad 2013-04-14 01:04:48

FYI - RFC description of 422: 11.2. 422 Unprocessable Entity The 422 (Unprocessable Entity) 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. For example, this error condition may occur if an XML request body contains well-formed (i.e., syntactically correct), but semantically erroneous, XML instructions.

@Steve Kallestad 2013-04-14 01:07:20

d'oh! I didn't realize I was adding to a nearly 3 year old comment. Sorry.

@Piskvor left the building 2013-08-02 15:39:26

@TurtlePowered: I see no problem with that - some of the discussions in the comments have been going on for years, literally.

@James Billingham 2014-01-02 14:04:33

And threads don't 'expire'. They need to be kept living or top google search results start to become inaccurate.

@Gherman 2016-09-21 08:50:58

I want the code and now I have it. I can't see a problem.

@bytedev 2020-01-29 03:50:18

IMO 422 is better than 400 or 403 because 422 can only be interpreted to mean one thing - the request body is well formed but invalid in some way. Where as 400 and 403 have other meanings (400 the request body is not well formed and 403 a user is authenticated but is not allowed to access a resource).

@Daniel Kmak 2014-12-03 22:17:18

Ember-Data's ActiveRecord adapter expects 422 UNPROCESSABLE ENTITY to be returned from server. So, if you're client is written in Ember.js you should use 422. Only then DS.Errors will be populated with returned errors. You can of course change 422 to any other code in your adapter.

@Suncat2000 2014-03-17 19:14:39

Status Code 304 Not Modified would also make an acceptable response to a duplicate request. This is similar to processing a header of If-None-Match using an entity tag.

In my opinion, @Piskvor's answer is the more obvious choice to what I perceive is the intent of the original question, but I have an alternative that is also relevant.

If you want to treat a duplicate request as a warning or notification rather than as an error, a response status code of 304 Not Modified and Content-Location header identifying the existing resource would be just as valid. When the intent is merely to ensure that a resource exists, a duplicate request would not be an error but a confirmation. The request is not wrong, but is simply redundant, and the client can refer to the existing resource.

In other words, the request is good, but since the resource already exists, the server does not need to perform any further processing.

@Sinaesthetic 2015-11-20 16:15:03

It was my understanding that 304 is intended for GET operations to assist with caching.

@sethcall 2013-04-04 17:40:59

200,300, 400, 500 are all very generic. If you want generic, 400 is OK.

422 is used by an increasing number of APIs, and is even used by Rails out of the box.

No matter which status code you pick for your API, someone will disagree. But I prefer 422 because I think of '400 + text status' as too generic. Also, you aren't taking advantage of a JSON-ready parser; in contrast, a 422 with a JSON response is very explicit, and a great deal of error information can be conveyed.

Speaking of JSON response, I tend to standardize on the Rails error response for this case, which is:

    "errors" :
        "arg1" : ["error msg 1", "error msg 2", ...]
        "arg2" : ["error msg 1", "error msg 2", ...]

This format is perfect for form validation, which I consider the most complex case to support in terms of 'error reporting richness'. If your error structure is this, it will likely handle all your error reporting needs.

@Jonah 2015-04-02 21:02:26

What about errors arising from interactions among the args. That is, arg1 is valid and arg2 is valid, but the combination of the two, with the the specific values sent, is not valid.

@sethcall 2015-04-08 19:54:59

I wouldn't over think it; just pick one that appears to own the relationship.

@snuggles 2016-10-13 19:18:19

or even just error on both args. As a user, I think I'd want to see the error on each of the fields that are conflicting, I think.

@bhathiya-perera 2019-01-23 12:05:34

Nice!. explicit is better than implicit

@Piskvor left the building 2010-07-20 13:24:04

  • Failed validation: 403 Forbidden ("The server understood the request, but is refusing to fulfill it"). Contrary to popular opinion, RFC2616 doesn't say "403 is only intended for failed authentication", but "403: I know what you want, but I won't do that". That condition may or may not be due to authentication.
  • Trying to add a duplicate: 409 Conflict ("The request could not be completed due to a conflict with the current state of the resource.")

You should definitely give a more detailed explanation in the response headers and/or body (e.g. with a custom header - X-Status-Reason: Validation failed).

@Piskvor left the building 2010-07-20 14:28:59

@deamon: That is not the specification, that's Wikipedia, i.e. someone's opinion on "what HTTP status codes mean"; note that the page essentialy says "this is what Apache means with 403, this is what IIS means with 403", and nowhere does it reference the official RFC. You seem to be repeating "403 means whatever Apache says". NOT. The actual RFC (which is the relevant document, not Apache's implementation, not IIS' implementation, not anyone else's implementation) is here:

@deamon 2010-07-20 14:37:36

I know this specification. The emphasis is on "forbidden" what means "access denied in any case".

@Piskvor left the building 2010-07-20 14:53:16

"10.4.4 403 Forbidden 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 the server does not wish to make this information available to the client, the status code 404 (Not Found) can be used instead." I see no emphasis there ("SHOULD/SHOULD NOT" are RFC 2119 keywords, not emphasis); that's your idea what "forbidden" means, not RFC's.

@pablobm 2011-10-14 20:19:39

I like this answer, but still see one small problem. According to the spec, when a 403 is returned, "the request SHOULD NOT be repeated". However, returning a 409 "is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request". In the case of a duplicate, I think 403 is then more appropriate, as you cannot really resolve the conflict (except by deleting the previous instance of the resource).

@user41871 2011-12-29 18:06:13

This is a good answer. I agree with Piskvor that an invalid payload isn't the same thing as a syntax error with the request.

@aleemb 2012-09-03 13:34:46

For the error message itself you should modify the reason phrase, so sending the header HTTP/1.0 403 Form validation errors is the cleanest way to go.

@Martin 2013-05-25 14:21:25

Having read the rfc this seems like the closest match in meaning for validation errors.

@tybro0103 2013-08-23 19:16:52

IMO, 422 "Unprocessable Entity" makes much more sense. My reasoning is that it's not that the server refuses to fulfill request, it's that the server can't fulfill the request.

@Piskvor left the building 2013-08-26 18:57:22

That might be an option, yes. I was trying to stay strictly within RFC2616 here - see the emotions that have flared up when @Julian Reschke has brought up 422 in a sibling answer:

@roberkules 2014-03-27 06:14:47

@Piskvor, as the X- prefix in custom HTTP headers is deprecated you could change your example to just Status-Reason: Validation failed.

@Piskvor left the building 2014-03-27 08:44:24

@roberkules: Deprecated? [citation-needed]

@roberkules 2014-03-27 09:35:24

@Piskvor left the building 2014-03-27 10:58:40

@roberkules: Interesting, thanks. I'll stick to Makes no recommendation as to whether existing "X-" parameters ought to remain in use or be migrated to a format without the "X-"; this is a matter for the creators or maintainers of those parameters. and keep it here as-is.

@Dan Passaro 2014-07-15 22:12:09

-1: 403 Forbidden implies the request was comprehensible; usually invalid input means an incomprehensible request

@Patrick Oscity 2015-07-10 12:09:30

From RFC 7231: “The 403 (Forbidden) status code indicates that the server understood the request but refuses to authorize it.”

@Piskvor left the building 2015-08-20 08:14:09

@PatrickOscity: See publication date and authors. I think that this SO question has influenced the wording of the section you are linking to ;)

@jimmont 2017-03-03 02:19:50

downvoted answer because it's no longer valid due to newer 2014 rfc7231, previous answer with 400/409 seems most accurate

@Beezer 2017-07-27 07:15:51

I up-voted this answer cause 403 is more indicative. If I have a 403 and there is no descriptive error message, at least I have a clue. 404 overlaps conditions and I would then require dot dig.

Related Questions

Sponsored Content

14 Answered Questions

[SOLVED] HTTP response code for POST when resource already exists

9 Answered Questions

[SOLVED] HTTP status code for update and delete?

5 Answered Questions

[SOLVED] What is the http-header "X-XSS-Protection"?

9 Answered Questions

[SOLVED] 400 vs 422 response to POST of data

1 Answered Questions

10 Answered Questions

[SOLVED] Understanding REST: Verbs, error codes, and authentication

  • 2010-01-04 19:55:36
  • Pekka
  • 132503 View
  • 601 Score
  • 10 Answer
  • Tags:   web-services rest

7 Answered Questions

5 Answered Questions

[SOLVED] After a POST, should I do a 302 or a 303 redirect?

Sponsored Content