Retry-After header in Rest API

Introduction

The Retry-After header tells a client when to try a request again after it was told to wait.

When a server is busy and wants the client to wait before retrying.

When a resource is temporarily unavailable and will be ready later.

When rate limits are reached and the client must pause before sending more requests.

When maintenance is happening and the server asks clients to retry later.

Syntax

Rest API

Retry-After: <HTTP-date>
Retry-After: <delta-seconds>

You can use either a date/time or a number of seconds.

The date/time is in HTTP-date format, like 'Wed, 21 Oct 2015 07:28:00 GMT'.

Examples

This tells the client to retry after 120 seconds (2 minutes).

Rest API

Retry-After: 120

This tells the client to retry after the given date and time.

Rest API

Retry-After: Wed, 21 Oct 2015 07:28:00 GMT

Sample Program

This is a simple HTTP response showing the Retry-After header telling the client to wait 60 seconds before retrying.

Rest API

HTTP/1.1 503 Service Unavailable
Retry-After: 60
Content-Type: text/plain

Service is busy. Please try again after 60 seconds.

Important Notes

Clients should respect the Retry-After header to avoid overloading the server.

If Retry-After is missing, clients decide when to retry on their own.

Using Retry-After helps improve user experience by giving clear wait times.

Summary

The Retry-After header tells clients when to try again.

It can use seconds or a date/time format.

It helps servers manage load and clients avoid repeated failures.