Rate limit headers (X-RateLimit) in Rest API - Step-by-Step Execution

Concept Flow - Rate limit headers (X-RateLimit)

Client sends API request

↓

Server checks request count

↓

Compare count with limit

↓

Send 429 error

↓

Send rate limit headers

↓

Client receives response with headers

↓

Client reads headers to manage requests

The client sends a request, the server checks if the request count exceeds the limit, then responds with rate limit headers showing usage and limits.

Execution Sample

Rest API

HTTP/1.1 200 OK
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1680000000

{ "data": "response" }

A server response showing rate limit headers indicating the total limit, remaining requests, and reset time.

Execution Table

Step	Client Request Count	Limit	Condition (Count < Limit)	Action	Response Headers
1	0	10	True	Process request	X-RateLimit-Limit: 10, Remaining: 9, Reset: timestamp
2	1	10	True	Process request	X-RateLimit-Limit: 10, Remaining: 8, Reset: timestamp
3	2	10	True	Process request	X-RateLimit-Limit: 10, Remaining: 7, Reset: timestamp
4	3	10	True	Process request	X-RateLimit-Limit: 10, Remaining: 6, Reset: timestamp
5	4	10	True	Process request	X-RateLimit-Limit: 10, Remaining: 5, Reset: timestamp
6	5	10	True	Process request	X-RateLimit-Limit: 10, Remaining: 4, Reset: timestamp
7	6	10	True	Process request	X-RateLimit-Limit: 10, Remaining: 3, Reset: timestamp
8	7	10	True	Process request	X-RateLimit-Limit: 10, Remaining: 2, Reset: timestamp
9	8	10	True	Process request	X-RateLimit-Limit: 10, Remaining: 1, Reset: timestamp
10	9	10	True	Process request	X-RateLimit-Limit: 10, Remaining: 0, Reset: timestamp
11	10	10	False	Reject request (429)	X-RateLimit-Limit: 10, Remaining: 0, Reset: timestamp

💡 At step 11, request count equals limit, condition is false, so server rejects request with 429 status.

Variable Tracker

Variable	Start	After 1	After 2	After 3	After 4	After 5	After 6	After 7	After 8	After 9	After 10	Final
Client Request Count	0	1	2	3	4	5	6	7	8	9	10	10
X-RateLimit-Remaining	10	9	8	7	6	5	4	3	2	1	0	0

Key Moments - 2 Insights

Why does the server send X-RateLimit-Remaining as 0 but still reject the request?

At step 11 in the execution_table, the request count equals the limit, so the server rejects the request with status 429 and shows Remaining as 0 to indicate no more requests allowed.

What does the X-RateLimit-Reset header mean?

The X-RateLimit-Reset header shows the time when the rate limit will reset, so the client knows when it can send requests again without being blocked.

Visual Quiz - 3 Questions

Look at the execution_table at step 5. What is the value of X-RateLimit-Remaining?

A 6

B 5

C 4

D 10

💡 Hint

Check the Response Headers column at step 5 in the execution_table.

At which step does the server start rejecting requests?

A Step 10

B Step 9

C Step 11

D Step 12

💡 Hint

Look for the step where Condition (Count < Limit) becomes False in the execution_table.

If the limit was increased to 15, what would happen to X-RateLimit-Remaining at step 10?

A It would be 5

B It would be 0

C It would be 10

D It would be 15

💡 Hint

Use the formula Remaining = Limit - Count from variable_tracker.

Concept Snapshot

Rate limit headers tell clients how many requests they can make.
X-RateLimit-Limit: total allowed requests.
X-RateLimit-Remaining: requests left.
X-RateLimit-Reset: time when limit resets.
Server sends 429 error if limit exceeded.

Full Transcript

This visual shows how rate limit headers work in an API. The client sends requests, and the server counts them. If the count is less than the limit, the server processes the request and sends headers showing the limit, remaining requests, and reset time. When the count reaches the limit, the server rejects further requests with a 429 error but still sends the headers. The X-RateLimit-Reset header tells the client when it can try again. This helps clients avoid sending too many requests and getting blocked.

Practice

1.

What does the X-RateLimit-Remaining header indicate in a REST API response?

easy

A. The time when the rate limit will reset.

B. The total number of API calls allowed per day.

C. The number of API calls made so far.

D. The number of API calls you can still make before hitting the limit.

Solution

1. Step 1: Understand the meaning of X-RateLimit-Remaining

   This header shows how many calls you have left before reaching the limit.

2. Step 2: Compare with other headers

   X-RateLimit-Limit is total allowed calls, X-RateLimit-Reset is reset time, so remaining calls is the count left.

3. Final Answer:

   The number of API calls you can still make before hitting the limit. -> Option D

4. Quick Check:

   Remaining calls = calls left [OK]

Hint: Remaining means how many calls you can still make [OK]

Common Mistakes:

• Confusing remaining with total limit
• Thinking it shows reset time
• Assuming it counts calls made

2.

Which of the following is the correct way to read the X-RateLimit-Reset header?

HTTP/1.1 200 OK
X-RateLimit-Reset: 1686000000

easy

A. It is a Unix timestamp indicating when the limit resets.

B. It shows the number of calls left before reset.

C. It is the total allowed calls per hour.

D. It shows the current time in ISO format.

Solution

1. Step 1: Identify the header type

   X-RateLimit-Reset usually gives a timestamp for when the limit resets.

2. Step 2: Interpret the value

   The value 1686000000 looks like a Unix timestamp (seconds since 1970).

3. Final Answer:

   It is a Unix timestamp indicating when the limit resets. -> Option A

4. Quick Check:

   Reset header = Unix timestamp [OK]

Hint: Reset header is always a timestamp in seconds [OK]

Common Mistakes:

• Thinking reset shows calls left
• Confusing reset with total limit
• Assuming reset is current time

3.

Given the following response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 250
X-RateLimit-Reset: 1686003600

How many API calls have been made so far?

medium

A. 750

B. 250

C. 1000

D. 1250

Solution

1. Step 1: Understand the headers

   Total allowed calls are 1000, remaining calls are 250.

2. Step 2: Calculate calls made

   Calls made = Total limit - Remaining = 1000 - 250 = 750.

3. Final Answer:

   750 -> Option A

4. Quick Check:

   1000 - 250 = 750 calls made [OK]

Hint: Calls made = Limit minus Remaining [OK]

Common Mistakes:

• Using remaining as calls made
• Adding limit and remaining
• Confusing reset time as calls made

4.

You receive these headers from an API:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: -10
X-RateLimit-Reset: 1686007200

What is the likely problem?

medium

A. The headers are missing the total calls made.

B. The limit is too low for the API.

C. The remaining calls cannot be negative; it's an error.

D. The reset time is in the past.

Solution

1. Step 1: Check the X-RateLimit-Remaining value

   Remaining calls cannot be negative; it should be zero or positive.

2. Step 2: Identify the error

   A negative remaining value indicates a bug or miscalculation in the API response.

3. Final Answer:

   The remaining calls cannot be negative; it's an error. -> Option C

4. Quick Check:

   Remaining calls must be ≥ 0 [OK]

Hint: Remaining calls can never be negative [OK]

Common Mistakes:

• Ignoring negative values as valid
• Confusing reset time with remaining
• Thinking limit is the problem

5.

You want to build a client that stops making API calls when the limit is reached and waits until reset. Given these headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1686009000

What should your client do?

hard

A. Continue making calls; the limit resets immediately.

B. Stop calls and wait until the reset timestamp before retrying.

C. Ignore the headers and retry after 1 minute.

D. Reset the remaining count manually and continue.

Solution

1. Step 1: Check remaining calls

   Remaining is 0, so no calls can be made now.

2. Step 2: Use reset time to wait

   The client should wait until the reset timestamp before making new calls.

3. Final Answer:

   Stop calls and wait until the reset timestamp before retrying. -> Option B

4. Quick Check:

   Remaining=0 means wait until reset [OK]

Hint: Stop calls at zero remaining; wait for reset time [OK]

Common Mistakes:

• Ignoring zero remaining and continuing calls
• Guessing reset time instead of using header
• Manually resetting counters in client