If you are building REST API via HTTP, your status codes should assist clients on choosing what to do next, even before the client read the response body or headers.
Below are some conventions that I found useful for my own project.
- 200 OK Server accepts the request and clients can proceed with its happy flow.
- 201 CREATED Server has created an object based on the request. Client can use the returned URL in the Location response header to access that object.
- 400 BAD REQUEST Server rejects the request due to invalid data. Client should show error message (may be returned from server) and should not re-attempt the same request.
- 401 UNAUTHORIZED Server rejects the credential in current request. Client should prompt for new credential and should not re-attempt any request with the same credential.
- 403 FORBIDDEN Server rejects the credential for that particular request. Client should not re-attempt until the request or the credential is changed.
- 404 NOT FOUND Server indicates the resource in the request does not exist. Client should cancel the request or start conflict resolution.
- 429 TOO MANY REQUEST This is usually from an API gateway with rate-limiting feature. However, server can also detect current resource consumption and use this status code to indicate resource overuse. Client should stop any automatic requests to server for a predefined interval or a time indicated in response headers or body.
- 500 INTERNAL SERVER ERROR Server encounters unexpected issue. Client can re-attempt the request, ideally with exponential back-off.
- 502 BAD GATEWAY This is usually from a misconfigured firewall or proxy. ARR in IIS also returns this status code after a connection timeout. Client can re-attempt this request with a long interval.
- 503 SERVICE UNAVAILABLE Server is off for maintenance. Client can switch to maintenance mode and re-attempt this request with a long interval.
Some additional notes:
- There are actually only 2 scenarios when client should really retry the request: response status code 5xx from server or networking issue. If you are retrying for a code 500 or 502, make sure you impose some limit (i.e. maximum retry, exponential back-off or a long enough interval) since all those retry can increase the load of the server and worsen the situation.
- Status code 502 can indicate a server timeout or connectivity issue. If you want to fine tune client behavior for this status code. You can impose a shorter timeout in the client to make sure that the status code always indicate connectivity issue.
- If you cache resources on client and delete them when receiving code 404, be extra careful with the implementation and make sure that the server is actually available before trusting that status code. A misconfigured IIS or an expired hosting package can make the whole site disappear and all your APIs suddenly returns 404. You may also consider using status code 410 GONE for objects that are deleted in the server.
- There are several other HTTP status codes that can be utilized by your API (https://en.wikipedia.org/wiki/List_of_HTTP_status_codes). In general, you should consider using Status code before response headers and body to indicate the type of the response.
If you have more suggestions or questions, please leave a comment below.