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.

Practice

1.

What is the main purpose of the Retry-After header in REST APIs?

easy

A. To provide the client's IP address to the server

B. To specify the content type of the response

C. To tell the client how long to wait before making another request

D. To indicate the server's current time

Solution

1. Step 1: Understand the role of Retry-After header

   The Retry-After header is used by servers to tell clients when they can retry a request after being told to wait.

2. Step 2: Match purpose with options

   To tell the client how long to wait before making another request correctly states that it tells the client how long to wait before retrying, which matches the header's purpose.

3. Final Answer:

   To tell the client how long to wait before making another request -> Option C

4. Quick Check:

   Retry-After = wait time before retry [OK]

Hint: Retry-After tells when to retry, not server info [OK]

Common Mistakes:

• Confusing Retry-After with content type headers
• Thinking Retry-After provides server time
• Assuming Retry-After sends client info

2.

Which of the following is a correct example of the Retry-After header syntax?

Retry-After: ?

easy

A. Wed, 21 Oct 2015 07:28:00 GMT

B. "120 seconds"

C. 120 seconds

D. After 2 minutes

Solution

1. Step 1: Review Retry-After header formats

   Retry-After accepts either a number of seconds (integer) or a HTTP-date string.

2. Step 2: Check each option

   120 seconds includes invalid text; "120 seconds" incorrectly quotes the number with text; Wed, 21 Oct 2015 07:28:00 GMT is a valid HTTP-date format; After 2 minutes is not a valid format.

3. Final Answer:

   Wed, 21 Oct 2015 07:28:00 GMT -> Option A

4. Quick Check:

   Retry-After = seconds or HTTP-date [OK]

Hint: Retry-After uses seconds or HTTP-date format only [OK]

Common Mistakes:

• Adding quotes around seconds value
• Using natural language like 'After 2 minutes'
• Using invalid date formats

3.

Given the following HTTP response header:

HTTP/1.1 503 Service Unavailable
Retry-After: 60

What should the client do?

medium

A. Wait 60 seconds before retrying the request

B. Retry the request immediately

C. Ignore the Retry-After header and retry after 5 seconds

D. Abort the request permanently

Solution

1. Step 1: Interpret the Retry-After header value

   The header value '60' means the client should wait 60 seconds before retrying.

2. Step 2: Match client action to header instruction

   Wait 60 seconds before retrying the request correctly instructs to wait 60 seconds before retrying, which follows the server's guidance.

3. Final Answer:

   Wait 60 seconds before retrying the request -> Option A

4. Quick Check:

   Retry-After: 60 means wait 60 seconds [OK]

Hint: Retry-After number means wait that many seconds [OK]

Common Mistakes:

• Retrying immediately ignoring Retry-After
• Assuming Retry-After is in milliseconds
• Treating Retry-After as a permanent failure

4.

Identify the error in this HTTP response header snippet:

HTTP/1.1 429 Too Many Requests
Retry-After: "30 seconds"

medium

A. The header name should be lowercase

B. Retry-After value should not be quoted or include text

C. Retry-After header is missing

D. Status code 429 is invalid

Solution

1. Step 1: Check Retry-After header format

   The Retry-After header must be either an integer number of seconds or a valid HTTP-date string without quotes or extra text.

2. Step 2: Identify the error in the given header

   The value "30 seconds" is quoted and includes text, which is invalid syntax.

3. Final Answer:

   Retry-After value should not be quoted or include text -> Option B

4. Quick Check:

   Retry-After must be seconds or date, no quotes/text [OK]

Hint: Retry-After value is raw seconds or date, no quotes [OK]

Common Mistakes:

• Adding quotes around Retry-After value
• Including descriptive text in Retry-After
• Confusing header case sensitivity

5.

A server wants to tell clients to retry after 2 minutes using the Retry-After header. Which is the best way to set this header to ensure compatibility?

hard

A. Retry-After: Wed, 21 Oct 2030 07:28:00 GMT (current time + 2 minutes)

B. Retry-After: "120 seconds"

C. Retry-After: After 2 minutes

D. Retry-After: 120

Solution

1. Step 1: Understand Retry-After header formats

   Retry-After accepts either an integer number of seconds or a valid HTTP-date string.

2. Step 2: Evaluate options for compatibility

   Retry-After: 120 uses integer seconds (120) which is simple and widely supported. Retry-After: "120 seconds" incorrectly quotes and adds text. Retry-After: Wed, 21 Oct 2030 07:28:00 GMT (current time + 2 minutes) uses a date but must be exact and updated dynamically, which is complex. Retry-After: After 2 minutes is invalid text.

3. Final Answer:

   Retry-After: 120 -> Option D

4. Quick Check:

   Use seconds as integer for simple Retry-After [OK]

Hint: Use integer seconds for Retry-After to ensure compatibility [OK]

Common Mistakes:

• Adding quotes or text to seconds value
• Using a fixed date without updating
• Writing natural language instead of valid format