Rate limit headers (X-RateLimit) in Rest API

Introduction

Rate limit headers tell you how many requests you can make to a server before it stops answering. They help keep the server safe from too many requests at once.

When you want to know how many API calls you have left before being blocked.

When building an app that talks to a server and you want to avoid sending too many requests.

When you want to show users how many requests they can still make.

When you want to handle errors caused by sending too many requests gracefully.

Syntax

Rest API

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 750
X-RateLimit-Reset: 1609459200

X-RateLimit-Limit shows the total number of allowed requests in a time window.

X-RateLimit-Remaining shows how many requests you can still make before hitting the limit.

X-RateLimit-Reset shows the time when the limit will reset, usually as a Unix timestamp.

Examples

This means you can make 5000 requests total, have 4999 left, and the limit resets at the given timestamp.

Rest API

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
X-RateLimit-Reset: 1672531200

You have used all 100 requests and must wait until the reset time to send more.

Rest API

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

Sample Program

This program calls an API, reads the rate limit headers, and prints how many requests you can make and when the limit resets.

Rest API

import requests
import time

url = 'https://api.example.com/data'
response = requests.get(url)

limit = response.headers.get('X-RateLimit-Limit')
remaining = response.headers.get('X-RateLimit-Remaining')
reset = response.headers.get('X-RateLimit-Reset')

print(f"Limit: {limit}")
print(f"Remaining: {remaining}")
if reset:
    reset_time = time.strftime('%Y-%m-%d %H:%M:%S', time.localtime(int(reset)))
    print(f"Reset at: {reset_time}")

Important Notes

Not all APIs use the same rate limit headers, but X-RateLimit is common.

The reset time is usually in Unix timestamp format, which counts seconds since 1970-01-01.

Always check the headers before making many requests to avoid being blocked.

Summary

Rate limit headers tell you how many API calls you can make.

X-RateLimit-Limit is the total allowed calls.

X-RateLimit-Remaining is how many calls you have left.

X-RateLimit-Reset tells when the limit resets.