Take the 2-minute tour ×

My REST API returns JSON.

I'm currently returning text/plain as the MIME type, but it feels funny. Should I be returning application/x-javascript or some other type?

The second question is with regard to the HTTP status code for error conditions. If my REST API is returning an error state, I am returning as JSON

{ result: "fail", errorcode: 1024, errormesg: "That sucked. Try again!" }

Should the HTTP status code remain at 200 OK?

share|improve this question
add comment

6 Answers

up vote 54 down vote accepted

The JSON spec suggests application/json, and that seems to be supported by the IETF and IANA registry.

On the second question, I think if the message handling fails in some way you should return a structured and standard error response as a JSON message; only if there is a failure to deliver the message to the backend handler for some reason should you consider an HTTP error code.

Update 2014-06-27: The days where clients (browsers) only worked with a 200 response are long past and the prevailing advice for RESTful APIs is to use HTTP response codes appropriate for the response, 2xx for successful responses (e.g. 201 Created for PUT; 204 No Content for DELETE) and 4xx and 5xx for all error conditions, including those from the API itself.

share|improve this answer
Thanks for the link to the JSON spec. I found another stackoverflow question that points to another MIME type "text/x-json". Not sure what's the difference. stackoverflow.com/questions/95554/… –  ashitaka Jan 1 '09 at 3:38
For practical reasons (say for example you've got Flex's horrific HTTP client in the mix), sometimes you have to use 200 for everything. However, under normal circumstances, you want to use the most appropriate HTTP status code for the situation. –  Bob Aman Oct 31 '09 at 5:08
@ashitaka: That other question specifically asks how to set JSON to text/x-json. It makes no claim as to that being the correct media-type for JSON. –  Lawrence Dol May 25 '11 at 18:50
add comment

I prefer to reply with both an HTTP error status and application specific payload.

share|improve this answer
It seems that David has left SO, but can anyone else support above statement and bring some arguments, why this is a good (or bad) practice? As per Software Monkey's answer above, I see, that returning a HTTP error with a valid JSON response is a wrong idea. Server should send back HTTP error only, if there is a true error. –  trejder Dec 18 '13 at 10:00
add comment

No, you shouldn't return 200 in an error condition.

It's ok to repeat the status code, or to include a more detailed error code in the response payload.

share|improve this answer
add comment

The proper Content-type to return is application/json, according to RFC 4627, which also registers the MIME type IANA (and indeed, it shows up on IANA's page). Of course, if you were to write a client, you would want to be more liberal in what you accept, and also accept others such as text/json and text/x-json.

Now, if there is an error you should not return HTTP 200, that's fundamentally non-RESTful. I know that sometimes there's not an exact match for your error, but choose the closest 4XX (client's fault) or 5XX (server's fault) errors in RFC 2616 Sections 10.4-10.5, and be more precise in the JSON.

share|improve this answer
add comment

The Content-Type has been provided by other answers several times but for the sake of completeness of the answer:

application/json (source: http://www.ietf.org/rfc/rfc4627.txt)

However, I would like to elaborate a bit on the HTTP status codes and your json response's status code and why I recommend keeping those two codes and their meanings separated.

There is a fundamental difference between those two status codes: The former represents the state of the client-server communication while the latter represents the state of your application. HTTP is a client-server communication protocol - as such, the HTTP status code should always reflect the state of this communication, not the state of your application. Here are a few example situations to describe this in practice:

  1. A client requests a resource at /users/123, but such resource (user) does not exist in the database: the HTTP code is 200 ( application successfully delivered the response to client ) and the json code should be something that the consumer can intrepret as "resource missing" or similar.

  2. A client requests a resource at /foo/123, but such REST endpoint does not exist: The HTTP code should be 404 because the server does not know where to route such request.

  3. A client requests a resource at /users/abc, but the application crashes while handling your request: the HTTP code is 500 in this case because an internal, unhandled error prevents the application from delivering the response to the client.

  4. A client requests a resource at /users/_, but the application does not accept _ (underscore) as a valid resource identifier: the HTTP code is 200 ( application successfully delivered the response to client ) and the json code should be something that the consumer can interpret as "invalid syntax" or similar.

share|improve this answer
add comment

Your Answer


