Notes on RESTful API Design This is a list of return codes in relation to a RESTful API design.
Some of the operations can have more than one outcome, so you need to decide on which one you find the most appropriate for your use case.
Operation HTTP Method Status Code On Success Notes Create POST 201 Created When the object is created immediately 202 Accepted When the object is accepted but not created immediately
400 Bad Request If the submitted data are malformed 404 Not Found If referenced objects do not exist 409 Conflict If you handle that the same object cannot be created more than once 422 Unprocessable Content If submitted data are validated and validation fails Read GET 200 OK When the object requested in included in the response 404 Not Found If referenced object/objects do not exist Update PUT 200 OK When the updated object is returned as part of the response 204 No Content When the updated object is not returned as part of the response 400 Bad request If the submitted data are malformed 404 Not Found If referenced object/objects do not exist 409 Conflict If you handle that the object cannot be updated inconsistently PATCH 200 OK When the updated object is returned as part of the response 204 No Content When the updated object is not returned as part of the response 400 Bad Request If the submitted data are malformed 404 Not Found If referenced object/objects do not exist Delete DELETE 200 OK When an object changes status to deleted or similar (soft delete ) and is returned as part of the response 202 Accepted When an object changes status to deleted or similar and is deleted a part of a garbage collection process or similar 204 No Content When an object is deleted immediately and the object is not returned 404 Not Found If referenced object do not exist
Status Code On Error Notes 401 Unauthorized If you receive a unauthenticated request, to a resource requiring authentication 403 Forbidden If you receive a authenticated but unauthorized request, to a resource requiring authorization 405 Method not allowed If you receive a HTTP method not supported 429 Too Many Requests If you support rate limiting and set limit is reached 500 Internal Server Error For you unhandled errors and errors server side
HTTP Method Idempotent Can become Idempotent POST No Yes PUT Yes PATCH No GET Yes HEAD Yes DELETE Yes OPTIONS Yes