14.37 Retry-After

The Retry-After response-header field can be used with a 503 (Service Unavailable) response to indicate how long the service is expected to be unavailable to the requesting client. This field MAY also be used with any 3xx (Redirection) response to indicate the minimum time the user-agent is asked wait before issuing the redirected request. The value of this field can be either an HTTP-date or an integer number of seconds (in decimal) after the time of the response.

   Retry-After  = "Retry-After" ":" ( HTTP-date | delta-seconds )

Two examples of its use are

   Retry-After: Fri, 31 Dec 1999 23:59:59 GMT
   Retry-After: 120

In the latter example, the delay is 2 minutes.

• Planned maintenance - this one is obvious, if your server is down within scheduled maintenance window, you can send Retry-After from proxy with precise information when to call back. Clients won't bother retrying earlier, of course IF they understand and honour this header
• Queue/thread pool full - if your request must be handled by a thread pool and it's full, you can estimate when next request can be handled. This requires bound queue (see: ExecutorService - 10 tips and tricks, point 6.) and rough estimate how long it takes for one task to be handled. Having this knowledge you can estimate when next client can be served without queueing.
• Circuit breaker open - in Hystrix you can query
• Next available token/resource/whatever

private static final HystrixCommand.Setter CMD_KEY = HystrixCommand.Setter
    .withGroupKey(HystrixCommandGroupKey.Factory.asKey("REST"))
    .andCommandKey(HystrixCommandKey.Factory.asKey("fetch"));

@RequestMapping(value = "/", method = GET)
public String fetch() {
    return fetchCommand().execute();
}

private HystrixCommand<String> fetchCommand() {
    return new HystrixCommand<String>(CMD_KEY) {
        @Override
        protected String run() throws Exception {
            //...
        }
    };
}

@RequestMapping(value = "/", method = GET)
public ResponseEntity<String> fetch() {
    final HystrixCommand<String> command = fetchCommand();
    if (command.isCircuitBreakerOpen()) {
        return handleOpenCircuit(command);
    }
    return new ResponseEntity<>(command.execute(), HttpStatus.OK);
}

private ResponseEntity<String> handleOpenCircuit(HystrixCommand<String> command) {
    final HttpHeaders headers = new HttpHeaders();
    final Integer retryAfterMillis = command.getProperties()
            .circuitBreakerSleepWindowInMilliseconds().get();
    headers.set(HttpHeaders.RETRY_AFTER, Integer.toString(retryAfterMillis / 1000));
    return new ResponseEntity<>(headers, HttpStatus.SERVICE_UNAVAILABLE);
}

@RequestMapping(value = "/", method = GET)
public ResponseEntity<String> fetch() {
    final HystrixCommand<String> command = fetchCommand();
    try {
        return new ResponseEntity<>(command.execute(), OK);
    } catch (HystrixRuntimeException e) {
        log.warn("Error", e);
        return handleHystrixException(command);
    }
}

private ResponseEntity<String> handleHystrixException(HystrixCommand<String> command) {
    final HttpHeaders headers = new HttpHeaders();
    if (command.isCircuitBreakerOpen()) {
        final Integer retryAfterMillis = command.getProperties()
            .circuitBreakerSleepWindowInMilliseconds().get();
        headers.set(HttpHeaders.RETRY_AFTER, Integer.toString(retryAfterMillis / 1000));
    }
    return new ResponseEntity<>(headers, SERVICE_UNAVAILABLE);
}

import java.time.format.DateTimeFormatter;

//...

final ZonedDateTime after5seconds = ZonedDateTime.now().plusSeconds(5);
final String httpDate = DateTimeFormatter.RFC_1123_DATE_TIME.format(after5seconds);

A note about auto-DDoS

Summary