Rate limit error responses in Rest API

Introduction

Rate limit error responses tell users when they have sent too many requests in a short time. This helps keep the service fair and working well for everyone.

When you want to stop a user from sending too many requests quickly.

To protect your server from overload or abuse.

To make sure all users get a fair chance to use the service.

When your API has limits on how many requests can be made per minute or hour.

To inform users politely that they need to wait before trying again.

Syntax

Rest API

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: <seconds>

{
  "error": "Rate limit exceeded",
  "message": "You have sent too many requests. Please wait before retrying."
}

The status code 429 means "Too Many Requests".

The Retry-After header tells the client how many seconds to wait before trying again.

Examples

This response tells the user to wait 60 seconds before sending more requests.

Rest API

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": "Rate limit exceeded",
  "message": "Try again in 60 seconds."
}

This response does not include Retry-After, so the client decides when to retry.

Rest API

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "error": "Rate limit exceeded",
  "message": "Please slow down your requests."
}

Sample Program

This small web server limits each user to 3 requests every 10 seconds. If the user sends too many requests, it returns a 429 error with a message and tells how many seconds to wait.

Rest API

from flask import Flask, request, jsonify
import time

app = Flask(__name__)

# Simple rate limit: max 3 requests per 10 seconds per IP
requests_log = {}

@app.route('/data')
def data():
    ip = request.remote_addr
    now = time.time()
    window = 10
    max_requests = 3

    # Clean old requests
    requests_log.setdefault(ip, [])
    requests_log[ip] = [t for t in requests_log[ip] if now - t < window]

    if len(requests_log[ip]) >= max_requests:
        retry_after = window - (now - requests_log[ip][0])
        response = jsonify({
            "error": "Rate limit exceeded",
            "message": f"Try again in {int(retry_after)} seconds."
        })
        response.status_code = 429
        response.headers['Retry-After'] = str(int(retry_after))
        return response

    requests_log[ip].append(now)
    return jsonify({"data": "Here is your data!"})

if __name__ == '__main__':
    app.run(debug=True)

Important Notes

Always include the Retry-After header if you want clients to know when to try again.

Use status code 429 specifically for rate limiting errors.

Be clear and polite in your error messages to help users understand what happened.

Summary

Rate limit errors use HTTP status 429 to tell users they sent too many requests.

The Retry-After header helps clients know when to retry.

Clear messages improve user experience and reduce confusion.