REST API Status codes (400 vs. 500)
Published by marco on
In a project that we’re working on, we’re consuming REST APIs delivered by services built by another team working for the same customer. We had a discussion about what were appropriate error codes to return for various situations. The discussion boiled down to: should a service return a 500 error code or a 400 error code when a request cannot be processed?
I took a quick look at the documentation for a couple of the larger REST API providers and they are using the 500 code only for catastrophic failure and using the 400 code for anything related to query-input validation errors.
Microsoft Azure Common REST API Error Codes
Code 400:
- The requested URI does not represent any resource on the server.
- One of the request inputs is out of range.
- One of the request inputs is not valid.
- A required query parameter was not specified for this request.
- One of the query parameters specified in the request URI is not supported.
- An invalid value was specified for one of the query parameters in the request URI.
Code 500:
- The server encountered an internal error. Please retry the request.
- The operation could not be completed within the permitted time.
- The server is currently unable to receive requests. Please retry your request.
Twitter Error Codes & Responses
Code 400:
“The request was invalid or cannot be otherwise served. An accompanying error message will explain further.”
Code 500:
“Something is broken. Please post to the group so the Twitter team can investigate.”
REST API Tutorial HTTP Status Codes
Code 400:
“General error when fulfilling the request would cause an invalid state. Domain validation errors, missing data, etc. are some examples.”
Code 500:
“A generic error message, given when no more specific message is suitable. The general catch-all error when the server-side throws an exception. Use this only for errors that the consumer cannot address from their end—never return this intentionally.”
“For input validation failure: 400 Bad Request + your optional description. This is suggested in the book “RESTful Web Services”.”