Skip to main content

Rate Limit Headers

Understanding and working with rate limit headers in API responses.

Response Headers​

Every Audian API response includes rate limit information in the response headers.

Standard Headers​

RateLimit-Limit: 500
RateLimit-Remaining: 342
RateLimit-Reset: 1640995200

Header Definitions​

HeaderTypeDescription
RateLimit-LimitintegerTotal requests allowed in current window
RateLimit-RemainingintegerRequests remaining before limit
RateLimit-ResetintegerUnix timestamp when limit resets

Rate Limit Header Examples​

Successful Request​

HTTP/1.1 200 OK
Content-Type: application/json
RateLimit-Limit: 500
RateLimit-Remaining: 427
RateLimit-Reset: 1640995200

Interpretation:

  • Total requests per window: 500
  • Requests you can still make: 427
  • Limit resets at: Feb 1, 2022, 00:00:00 UTC

Near Limit​

HTTP/1.1 200 OK
RateLimit-Limit: 500
RateLimit-Remaining: 5
RateLimit-Reset: 1640995200

Warning: Only 5 requests remaining before you hit the limit.

At Limit​

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 500
RateLimit-Remaining: 0
RateLimit-Reset: 1640995200
Retry-After: 45

You've hit the limit and must wait 45 seconds.

Retry-After Header​

When rate limited (429 response), the Retry-After header specifies how long to wait.

Format​

Retry-After: 60

The value is in seconds. Always respect this value when retrying.

Example​

HTTP/1.1 429 Too Many Requests
Retry-After: 120

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests"
  }
}

Wait 120 seconds before making another request.

Reading Headers in Different Languages​

JavaScript/Node.js​

const response = await fetch('https://api.audian.com:8443/v2/numbers', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

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

console.log(`Limit: ${limit}`);
console.log(`Remaining: ${remaining}`);
console.log(`Reset: ${new Date(reset * 1000)}`);

Python​

import requests

response = requests.get(
    'https://api.audian.com:8443/v2/numbers',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

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

print(f"Limit: {limit}")
print(f"Remaining: {remaining}")
print(f"Reset: {reset}")

Ruby​

require 'net/http'
require 'json'

uri = URI('https://api.audian.com:8443/v2/numbers')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'

response = http.request(request)

limit = response['RateLimit-Limit']
remaining = response['RateLimit-Remaining']
reset = response['RateLimit-Reset']

puts "Limit: #{limit}"
puts "Remaining: #{remaining}"
puts "Reset: #{reset}"

PHP​

$ch = curl_init('https://api.audian.com:8443/v2/numbers');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Auth-Token: YOUR_API_KEY'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$info = curl_getinfo($ch);

$limit = isset($info['RateLimit-Limit']) ?
    $info['RateLimit-Limit'] : null;
$remaining = isset($info['RateLimit-Remaining']) ?
    $info['RateLimit-Remaining'] : null;
$reset = isset($info['RateLimit-Reset']) ?
    $info['RateLimit-Reset'] : null;

echo "Limit: $limit\n";
echo "Remaining: $remaining\n";
echo "Reset: $reset\n";

Go​

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET",
        "https://api.audian.com:8443/v2/numbers", nil)
    req.Header.Add("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)

    limit := resp.Header.Get("RateLimit-Limit")
    remaining := resp.Header.Get("RateLimit-Remaining")
    reset := resp.Header.Get("RateLimit-Reset")

    fmt.Printf("Limit: %s\n", limit)
    fmt.Printf("Remaining: %s\n", remaining)
    fmt.Printf("Reset: %s\n", reset)
}

Java​

import java.net.HttpURLConnection;
import java.net.URL;

public class RateLimitExample {
    public static void main(String[] args) throws Exception {
        URL url = new URL("https://api.audian.com:8443/v2/numbers");
        HttpURLConnection conn =
            (HttpURLConnection) url.openConnection();

        conn.setRequestProperty("Authorization",
            "Bearer YOUR_API_KEY");

        String limit = conn.getHeaderField("RateLimit-Limit");
        String remaining = conn.getHeaderField("RateLimit-Remaining");
        String reset = conn.getHeaderField("RateLimit-Reset");

        System.out.println("Limit: " + limit);
        System.out.println("Remaining: " + remaining);
        System.out.println("Reset: " + reset);
    }
}

Monitoring Rate Limit Usage​

Track Usage Pattern​

import time
import requests

api_key = "YOUR_API_KEY"
headers = {"Authorization": f"Bearer {api_key}"}

for i in range(5):
    response = requests.get(
        'https://api.audian.com:8443/v2/numbers',
        headers=headers
    )

    remaining = response.headers.get('RateLimit-Remaining')
    print(f"Request {i+1}: {remaining} remaining")
    time.sleep(1)

Calculate Remaining Time​

import time
from datetime import datetime

reset_timestamp = int(response.headers.get('RateLimit-Reset'))
current_time = int(time.time())

seconds_until_reset = reset_timestamp - current_time
minutes_until_reset = seconds_until_reset / 60

print(f"Limit resets in {seconds_until_reset} seconds")
print(f"That's {minutes_until_reset:.1f} minutes")

Set Up Alerts​

def check_rate_limit(response):
    remaining = int(response.headers.get('RateLimit-Remaining', 0))
    limit = int(response.headers.get('RateLimit-Limit', 100))
    percentage = (remaining / limit) * 100

    if percentage < 10:
        print("WARNING: Below 10% rate limit remaining!")
    elif percentage < 25:
        print("CAUTION: Below 25% rate limit remaining")
    else:
        print(f"OK: {percentage:.0f}% remaining")

Rate Limit Header Interpretation​

Healthy State​

RateLimit-Limit: 500
RateLimit-Remaining: 450
RateLimit-Reset: 1640995200

You're using 10% of your limit. Continue normally.

Caution Zone​

RateLimit-Limit: 500
RateLimit-Remaining: 50
RateLimit-Reset: 1640995200

You're using 90% of your limit. Consider implementing backoff.

Danger Zone​

RateLimit-Limit: 500
RateLimit-Remaining: 10
RateLimit-Reset: 1640995200

You're using 98% of your limit. Slow down requests.

Limit Exceeded​

RateLimit-Limit: 500
RateLimit-Remaining: 0
RateLimit-Reset: 1640995200
Retry-After: 60

You've hit the limit. Wait and retry.

Reset Timestamp Format​

The RateLimit-Reset header uses Unix timestamp (seconds since January 1, 1970).

Convert to Human-Readable​

JavaScript:

const resetTime = new Date(parseInt(reset) * 1000);
console.log(resetTime.toISOString());

Python:

from datetime import datetime
reset_time = datetime.fromtimestamp(int(reset))
print(reset_time.isoformat())

Ruby:

require 'time'
reset_time = Time.at(reset.to_i).iso8601
puts reset_time

Custom Rate Limit Headers​

Some premium plans may have additional headers:

X-RateLimit-Limit-Per-Second: 10
X-RateLimit-Remaining-Per-Second: 7
X-RateLimit-Burst-Capacity: 50

Check your plan documentation for custom headers.

Best Practices​

  1. Always Check Headers: Never assume you have quota
  2. Respect Retry-After: Wait the specified time before retrying
  3. Track Remaining: Log the remaining count
  4. Alert Early: Set alerts at 25% and 10% remaining
  5. Plan Requests: Spread requests to avoid bursts
  6. Monitor Trends: Track usage patterns over time

FAQ​

Q: Why do I sometimes have more remaining requests? A: Using sliding windows, old requests fall out of the window as time passes.

Q: Can I trust the remaining count to be exact? A: The remaining count is accurate at response time but changes as time passes.

Q: What if reset time is in the past? A: The limit should have reset. Try again immediately.

Q: Do all endpoints include rate limit headers? A: Yes, all Audian API endpoints include rate limit headers.

Q: Can I see rate limit headers in browser dev tools? A: Yes, check the Response Headers tab in Network requests.