CODEWITHSUNDEEP
c#resthttp
Vinicius Gonçalves
Vinicius Gonçalves

Reputation: 2724

Correct way to use the 503 (Service Unavailable) status code

I've a simple API endpoint "api/machines/sum" that integrates with another API service to process a value.

Sometimes the API I am integrating can be offline/unavailable. So, I tought to return 503 - Service unavailable from my API, since my service can't process anything with the dependent API offline

My API service is runing ok, but dependents no.

Semantically, the "service unavailable" description makes sense to me. Is it a correct way for the 503 status code use?

sample:

public async Task<IActionResult> Sum(string value)
{
    try
    {
        ProcessValueFromAnotherAPI(id);
    }
    catch (AppIntegrationException)
    {
        return StatusCode(StatusCodes.Status503ServiceUnavailable, "custom message");
    }
}

Upvotes: 4

Views: 6633

Answers (2)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57377

Sometimes the API I am integrating can be offline/unavailable. So, I tought to return 503 - Service unavailable from my API, since my service can't process anything with the dependent API offline

Sounds good to me.

The fact that your origin server has external dependencies is an implementation detail; and is not the sort of thing that we normally describe in the HTTP metadata.

You could choose to use 500 Internal Error instead. The primary difference, and what makes 503 Service Unavailable interesting, is that we have Retry-After semantics available -- we can communicate to the client in a standardized way our current estimate of when service will be restored.

Another possibility would be to roll your own status code.

599 BLAME SOMEONE ELSE

general purpose components that don't recognize the code will treat it like a 500 Internal Error. The risk is that a later standardization effort will register your code, and then you'll have a mess to clean up.

If you think you have a case that these semantics here are generally available, then you could proceed to write a specification and work through the process of adding your code to the registry.

All server errors SHOULD include a representation send a representation of the explanation of the error.

So the information that is of interest to the entity that generated the request, but not necessarily of interest to general purpose components, should be present in the message-body of the HTTP response.

Upvotes: 3

Mark C.
Mark C.

Reputation: 6460

It's an interesting question - because often times a 503 refers to the actual service you're calling (in this case, your API). I think it's more fitting to return a normal response from your API but maybe with an object dictating the status :

{ "status" : "offline" }

This communicates to the caller that your API is healthy, and it's not ambiguous if your API were to actually return a 503.

Upvotes: 5

Related Questions