Retry-After header in Rest API - Step-by-Step Execution

Concept Flow - Retry-After header

Client sends request

↓

Server processes request

↓

Server decides to delay response

↓

Server sends response with Retry-After header

↓

Client reads Retry-After value

↓

Client waits specified time

↓

Client retries request

The Retry-After header tells the client how long to wait before trying the request again.

Execution Sample

Rest API

HTTP/1.1 503 Service Unavailable
Retry-After: 120

Service is temporarily down, please retry after 120 seconds.

Server responds with 503 status and Retry-After header telling client to wait 120 seconds before retrying.

Execution Table

Step	Action	Server Response	Client Behavior
1	Client sends request	No response yet	Waiting for server
2	Server processes request	Processing	Waiting
3	Server decides service unavailable	503 Service Unavailable	Receives response
4	Server adds Retry-After header	Retry-After: 120	Reads Retry-After value
5	Client waits 120 seconds	Response sent	Waits 120 seconds
6	Client retries request after wait	New request received	Sends request again

💡 Client retries only after waiting the time specified in Retry-After header.

Variable Tracker

Variable	Start	After Step 4	After Step 5	Final
Retry-After value	None	120 seconds	120 seconds (countdown)	None (after retry)
Client wait state	Idle	Idle	Waiting	Retrying

Key Moments - 3 Insights

Why does the client wait before retrying?

Because the Retry-After header tells the client how many seconds to wait, as shown in step 4 and 5 of the execution_table.

What happens if the Retry-After header is missing?

The client may retry immediately or use its own logic, but here the Retry-After header guides the wait time (step 4).

Is the Retry-After value always in seconds?

No, it can be seconds or a HTTP-date, but in this example it is seconds (120), as shown in the execution_sample.

Visual Quiz - 3 Questions

Look at the execution_table, what does the client do at step 5?

A Immediately retries the request

B Sends a new request without waiting

C Waits for the time specified in Retry-After header

D Ignores the Retry-After header

💡 Hint

Check the 'Client Behavior' column at step 5 in the execution_table.

At which step does the server send the Retry-After header?

A Step 2

B Step 4

C Step 3

D Step 6

💡 Hint

Look at the 'Server Response' column in the execution_table for when Retry-After appears.

If the Retry-After value was 60 instead of 120, how would the variable_tracker change?

A Retry-After value after step 4 would be 60 seconds

B Client wait state would be 'Idle' after step 5

C Retry-After value would be None at step 4

D Client retries immediately at step 5

💡 Hint

Check the 'Retry-After value' row in variable_tracker after step 4.

Concept Snapshot

Retry-After header tells client how long to wait before retrying.
Used in responses like 503 Service Unavailable.
Value can be seconds or a date.
Client reads header, waits, then retries.
Helps avoid overload and manage retries politely.

Full Transcript

The Retry-After header is sent by a server when it wants the client to wait before retrying a request. The client sends a request, the server processes it, and if the service is unavailable, the server responds with a 503 status and includes the Retry-After header with a wait time in seconds or a date. The client reads this header, waits the specified time, and then retries the request. This helps prevent clients from retrying too quickly and overwhelming the server.