Response status codes

HTTP specification defines standard status codes, and REST API can use the same status codes to deliver the results of a client request.

 The status code categories and a few associated REST API rules are as follows so that the APIs can apply those rules according to the process status:

• 1xx: Informational: This provides protocol-level information
• 2xx: Success: Client requests are accepted (successfully), as in the following examples:
  • 200: OK
    • Use for indicating client request success
    • Do not use to communicate the errors in the response body
  • 201: Created
    • Apply for successful resource creation
  • 202: Accepted
    • Use for reporting the successful asynchronous action
  • 204: No content
    • When an API wants to send empty or no content in the response body
• 3xx: Redirection: Client requests are redirected by the server to the different endpoints to fulfil the client request:
  • 301: Moved Permanently
    • Use for relocated resources
  • 302: Found
    • Please note not to use 302, as it would create confusion among the developers related to the initiation of automatic redirections from the client
  • 303: See other
    • Apply to refer the client to a different URI (in place of 302, it's recommended the API should use 303)
  • 304: Not modified
    • Use so that the client can preserve bandwidth
    • Use in conjunction with conditional HTTP requests
  • 307: Temporarily redirect
    • Use to indicate to the clients to resubmit the request to another URI
• 4xx: Client error: Errors at client side:
  • 400: Bad request
    • Can be used to indicate generic or nonspecific failures
  • 401: Unauthorized
    • Apply for unauthorized access from the client side or problem with the client credentials
  • 403: Forbidden
    • Use to forbid access regardless of the authorization state
    • Use to enforce application-level permission (allowed to access only a few resources and not all the resources)
  • 404: Not found
    • Must use when client request doesn't map to any of the API resources
  • 405: Method not allowed
    • Use when the client accesses unintended HTTP methods
    • Example read-only resource might only support GET and HEAD , and the client tried to use PUT or DELETE
    • Please note that 405 response should be part of the Allow header (Allow—GET. POST)
  • 406: Not acceptable
    • Must use when the server can't serve the requested media type
  • 409: Conflict
    • Use for client violation of a resource state
    • An example could be an API returns this error when the client tries to delete a non-empty store resource
  • 412: Precondition failed
    • Use to support conditional operations. The client sends one or more preconditions in the request headers to indicate to the API to execute only those conditions that are satisfied; if not, the API should send a 412 error code.
  • 415: Unsupported media type
    • Must be used when the API is not able to process the request's payload media type (indicated in the content-type request header)
• 5xx: Server error: These relate to errors at server side:
  • 500: Internal server error
    • Use to report the API/server-side issues, and when it's certainly not the client's side fault