HTTP Status Codes to use in RESTful Web Services

Below is a table explaining the HTTP status codes I like to use when writing RESTful web service end-points. By using the codes consistently it allows me to have a clear understanding when and where these codes needs to be returned from the server side.

Response Code Description Interpretation
200 OK Success
400 Bad Request Validation/Business Rule Failure
401 Unauthorised Invalid Credentials
403 Forbidden Invalid/Expired Token
404 Not Found Invalid End-Point
500 Internal Error Internal exception on end-point

Explanation of each code:

OK – 200

Each successful request that was made to the server, which passed all server side validation and logic, for example:

  •  valid security tokens/credentials,
  • valid end-point,
  • validated data
  • successful execution of business logic
  • successful CRUD operations

Bad Request – 400

Data supplied via the model to the end-point does not validate (typically POST verbs) or pass business rules. These are typically “hard validations” and always need to occur on the server-side.

(“Soft validations” occurs on the client side to ensure that appropriate data goes into the model before it is sent to the web service.)

Unauthorised – 401

401 could indicate that an end-point was invoked

  • without correct authentication credentials,
  • a malformed security key/token,
  • use of an already used token, or
  • failure of an internal security check (ban by IP).

401 is a permanent failure, and should also be logged for further security scrutiny as this may indicate attacks on the endpoints that may reveal vulnerabilities.

Forbidden – 403

“Forbidden” can be seen as tokens that might have expired in some way, and needs to be re-authenticated before use. This would typically be when the token/key has expired, and doesn’t meet any of the 401 criteria.

403 is a recoverable error.

Leave a Reply

Your email address will not be published. Required fields are marked *