In what circumstances a REST API should return HTTP Status 503
The standard says:
10.5.4 503 Service Unavailable. The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay.
REF: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
If the server is having lock contension at the database access level, should the server return 503 in such cases. Or is the 503 status meant for:
- Network overload
- DOS type situations
- Maxed out load balancing
- Explicit maintenance window.
What other circumstances it makes sense to return HTTP status 503.
Any detailed clarification is much appreciated.
Answer
Let's say the service experiences a contention for the database. There are no rules as to what a server MUST do. You may however choose to return a 503 if you believe the issue is temporary and will be resolved after some time. You can specify the Retry-After header to inform the caller when he could retry. This is especially useful to allow the caller to automatically recover from the issue. You may use it for some of your other scenarios as well as the callers could automatically retry after the specified period.
The status codes serve 2 purposes
- Let the caller know what happened
- Let the caller know what he could do next
Sending the caller a 503 with Retry-After provides more options to the caller than say sending a 500. Of course the caller is free to totally ignore the Retry-After and treat it as a 500 but you as a service provider are providing more information and options.