Help your client even more
Sometime when one of your favorite website has issue you can see something like that:
It’s very small thing, but it can help your client, if you respond with information that action succeeded or failed, and HTTP has easy, lean solution for that, Status Codes.
Why even bother with status codes
For me the biggest advantage is that I just need to look at status code and I know what happened more or less. You don’t need to read response from API to learn that everything was OK, You don’t need to read error message when something went wrong as well, status code tells you more or less what the problem is.
Additionally status code is separate property in response object in js/C# etc. client. So you can specify that your client will do special action when status isn’t success i.e its code is from 4xx to 5xx. If we would ignore status codes then we would need to check response message if it contains “error” string.
Success
200 – OK
Action succeeded, response contains data. Used when returning data from server. Mostly response from GET request.
201 – Created
New resource has been created. Used after POST request, when client store new resource in data storage. Usually response contains only required information and URL to action which will return whole resource.
202 – Accepted
The request has been accepted for processing, but the processing has not been completed. Usually used in micro-service architecture, when we create task that will take some time to finish.
204 – No Content
Action succeeded, but response is empty, used with DELETE verb, when resource was successfully removed, or when response is empty. Some browser will show warning when we return 200 without content.
304 – Not Modified
The client can use cached data.
Failure
400 – Bad Request
The request didn’t pass server-side validation or cannot be served. Bad Request is used only when it was client error, that means client can change his request to make it work.
For example when adding new student, client didn’t provide name of student, API will return Bad Request, but when client provide name it will create new student.
Additionally the exact error should be explained in the error payload. E.g. “Student name is required.”
401 – Unauthorized
The request requires a user authentication. Client has to login to API, because API doesn’t know who want to use it.
403 – Forbidden
User is authenticated, but lack of permissions.
It’s worth to mention difference between Authentication and Authorization and little inconsistency.
- Authentication is the process of verifying who you are. For example sign in with your username and password.
- Authorization is the process of verifying that you have permission to do something for example load data, remove resource etc.
HTTP made mistake here, status code 401 - Unauthorized is used to inform user that he isn’t authenticated, and 403 - Forbidden is used to inform that user is authenticated but doesn’t have permission.
404 – Not found
Resource could not be found, for example student with name Martin doesn’t exist. It’s also used for wrong urls, when endpoint doesn’t exist.
Every time client wants to access some resource and it wasn’t found we should respond with 404, even if client wants to update or delete resource that not exist.
405 – Not Allowed
We can use 405 when one action on resource is not supported. For example we can read, create and update students, but we can’t remove them yet. Additionally we need to respond with header Allow which contains list of the target resource’s currently supported methods, in our example GET, POST, PUT.
406 – Not Acceptable
406 error code is used when server doesn’t have current representation that would be acceptable to the user agent (for example browser), according to Accept header of request.
In normal language when user wants us to respond with XML, but we support only JSON.
409 – Conflict
Conflict can be used when multiple users update the same resource at the same time. Normally last person would override changes on resource, it’s not acceptable, because both users would think they changed resource when in truth only last one did.
Digression here, Entity Framework provide feature to track concurrent operations, it will throw exception so second update/delete on the same row will not be committed.
415 – Unsupported Media Type
It is connected to `406 error` but it’s reversed. Server respond with 415 when payload is in a format not supported by this method.
Like before, we’re supporting only JSON, but client send to use request with XML body.
500 – Internal Server Error
Every not caught exception ends with 500 error code. We can respond with this error every time something not expected happened.
We should catch errors in global filter, the stack trace should be logged. Additionally we shouldn’t return it as response, because it may contain vulnerable information.
4xx vs 5xx errors
The 4xx class of status code is intended for cases in which the client seems to have erred. That means everything is as design and client can fix their own errors by changing request.
Response status codes beginning with the digit “5” indicate cases in which the server is aware that it has erred or is incapable of performing the request. That means it’s server’s fault and only server can deal with error.
Outro
There are a lot more status codes in HTTP standard. I’ve presented only the most important for new web developers. Don’t bother remembering them. You’ll learn by using it. Consider this post as status codes reminder.