REST client error handling - 503 Error

The HTTP 503 Service Unavailable server error response code indicates that the server is temporarily not ready to handle the request.

Common causes of the 503 HTTP Status Code:

• The server is down for a scheduled maintenance
• The server is overloaded due to too much traffic

In any case, the server will relieve itself after some delay.

A REST client cannot control what happens on the server side

Business-to-business (B2B) is a typical scenario where one business acts as a client and the other acts as a server.

A client-side company doesn’t care if there is a monolithic or microservice architecture on the server side.

We have implemented a web client that retrieves data from a thousand articles on each request.

We need to send 50 thousand items. We reuse the following method to send a thousand articles every time. But suddenly, the external API throws an HTTP 503 status code. To avoid our REST client aborting the process, we catch the exception and put the error into a logger, and the program continues with the following one thousand articles.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
public Response getArticles(StringJoiner arrayOf1000Articles) throws Exception {
   
  MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
  map.add("content", arrayOf1000Articles.toString());
  HttpEntity<MultiValueMap<String, String>> request = new HttpEntity<>(map, headers);

  Response response = null;
  try {
    response = new RestTemplate().postForObject(URL_SERVER + "/articles/search", request, Response.class);
  } catch (Exception e) {
    logger.error("Error in getArticles " + e.getMessage());
  }

  return response; 
}

Well, looking at our internal server logs - logger - won’t help to retry the request that failed. Sometimes we usually call the company that takes care of the external server. Usually, they report that there was a Service outage response.

What this 503 error suggests is a retry action from our REST client to deal with external server errors.

How does the REST Client automate a retry action?

As developers, we need to anticipate and automate retrying the request with a certain number of attempts (MAX_TRIALS). If the server error persists, we need to inform our users about the failed request’s content.

The following code implementation handles 503 Service Unavailable Error.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
public Response getArticles(StringJoiner arrayOf1000Articles) throws Exception {
   
  MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
  map.add("content", arrayOf1000Articles.toString());
  HttpEntity<MultiValueMap<String, String>> request = new HttpEntity<>(map, headers);
  
  boolean success = false;
  int MAX_TRIALS = 3;
  int nextTrial = 1;
  Response response = null;
  do {
    try {
      response = new RestTemplate().postForObject(URL_SERVER + "/articles/search", request, Response.class);
      success = true;
    } catch (Exception e) {
      logger.error("Error in getArticles " + e.getMessage());
      nextTrial++;
    }
  } while (!success && nextTrial <= MAX_TRIALS);
 
  if (!success)
    informError("Error in getArticles " + arrayOf1000Articles.toString());
 
  return response; 
}

For simplicity and learning purposes, we assume we receive an HTTP status code of 503 within the try & catch block.

You can simulate a HTTP status code 503 by calling the httpstat.us service.

Call the service httpstat.us with the desired response code in the URL path.

1
$ curl -v http://httpstat.us/503

The response looks like this:

1
2
3
4
5
6
7
> GET /503 HTTP/1.1
> Host: httpstat.us
> User-Agent: curl/7.54.0
> Accept: */*
>
< HTTP/1.1 503 Service Unavailable
...

When you need to analyze several server logs in a distributed system, read the article Implementing hot-warm architecture in Elasticsearch.

Best Practices for Handling 503 Errors

• Respect the Retry-After Header: If the server includes this header, wait before retrying.
• Implement Exponential Backoff: Retry after increasing delays (e.g., 1s, 2s, 4s).
• Set a Maximum Retry Limit: Avoid infinite loops; define a max retry count.
• Log Errors for Debugging: Persistent 503 errors may indicate a backend issue.
• Fallback Mechanisms: Consider alternative servers or cached responses.

Jobs in the tech industry are expected to grow exponentially in the next few years. If you plan to enter the job market soon, you must know that companies will evaluate your problem-solving skills based on data structures and algorithms, and you will need to face a complex problem on a blackboard.

Please donate if you can. Every contribution helps, and your donation can help maintain and improve this website, no matter how small.

  Stay Connected!. Follow me to get my latest articles.