Proper status codes for JSON responses to Ajax calls?

Question

My project is returning JSON to Ajax calls from the browser. I'm wondering what the proper status code is for sending back with responses to invalid (but successfully handled) data submissions.

For example, jQuery has the following two particular callbacks when making Ajax requests:

success: Fired when a 200/2xx status code is delivered along with the response.

error: Fired when 4xx, 5xx, etc, status codes come back with the response.

If a user attempts to create a new "Person" object, I send back a JSON representation of the newly created object upon success, thus giving javascript access to the necessary unique ID's for the new object, etc. This, of course, is sent with a 200 status code.

If a user submits malformed or invalid data (say, an invalid/incomplete "name" field), I would like to send back the validation error messages via JSON. (I don't see why this would be a bad thing).

My question is: in doing so, should I send a 200 status code, because I successfully handled their invalid data? Therefore, I'd be using the jQuery success callback, but simply check for errors...

Or, should I use a 4xx status code, perhaps 'Bad Request', because the data they sent me is invalid? (and thus, use the error callback to do the necessary client-side notifications).

Answer 1

I agree with the 400 Bad Request response.

For inspiration you could have a look at how Twitter (widely used JSON service) does this: https://dev.twitter.com/overview/api/response-codes

Code Text Description

• 200 OK - Success!
• 304 Not Modified - There was no new data to return.
• 400 Bad Request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. Requests without authentication are considered invalid and will yield this response.
• 401 Unauthorized - Missing or incorrect authentication credentials. Also returned in other circumstances (for example, all calls to API v1 endpoints return 401).
• 403 Forbidden - The request is understood, but it has been refused or access is not allowed. An accompanying error message will explain why. This code is used when requests are being denied due to update limits . Other reasons for this status being returned are listed alongside the response codes in the table below.
• 404 Not Found - The URI requested is invalid or the resource requested, such as a user, does not exists. Also returned when the requested format is not supported by the requested method.
• 406 Not Acceptable - Returned when an invalid format is specified in the request.
• 410 Gone - This resource is gone. Used to indicate that an API endpoint has been turned off.
• 420 Enhance Your Calm Returned when an application is being rate limited .
• 422 Unprocessable Entity - Returned when an image uploaded to POST account / update_profile_banner is unable to be processed.
• 429 Too Many Requests - Returned when a request cannot be served due to the application’s rate limit having been exhausted for the resource. See Rate Limiting .
• 500 Internal Server Error = Something is broken. Please post to the developer forums with additional details of your request, in case others are having similar issues.
• 502 Bad Gateway - Twitter is down or being upgraded.
• 503 Service Unavailable - The Twitter servers are up, but overloaded with requests. Try again later.
• 504 Gateway Timeout - The Twitter servers are up, but the request couldn’t be serviced due to some failure within our stack. Try again later.