Skip to content

API rate limits

Enterprise feature

The REST API is available on Enterprise plans. Compare plans to find the right fit for your team.

Rate limits protect system stability and ensure fair usage across all API consumers. When your application exceeds the allowed request rate, the API returns a throttling response so you can adjust your request pattern.

How rate limiting works

Every API key is subject to request-rate limits. The API tracks your usage over a rolling time window and begins rejecting requests once the limit is reached.

Rate limit information is included in response headers on every request:

Header Description
X-RateLimit-Limit Maximum requests allowed in the current window
X-RateLimit-Remaining Requests remaining before throttling begins
X-RateLimit-Reset Unix timestamp when the window resets
Retry-After Seconds to wait before retrying (only on 429 responses)

Rate limit response

When you exceed the rate limit, the API returns HTTP 429 Too Many Requests:

{
  "success": false,
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please try again later.",
  "retry_after": 60
}

The Retry-After header and retry_after field in the response body both indicate how many seconds to wait before sending your next request.

Rate limit tiers

Different operation types have different rate limits to balance throughput and system protection:

Tier Operations Relative limit
Standard reads Listing and retrieving records (GET) Highest throughput
Single-entity reads Retrieving a specific record by ID High throughput
Write operations Creating and updating records (POST, PUT, PATCH) Moderate throughput
Daily global Total API calls across all endpoints Generous daily allowance

Per-key limits

Rate limits apply per API key. If you need higher throughput, contact your account manager to discuss custom limits for your integration.

Check your remaining quota

Monitor the X-RateLimit-Remaining header on every response to stay within your limits proactively.

Best practices

Cache responses

Avoid fetching the same data repeatedly. Cache API responses on your side and refresh them at sensible intervals.

import requests
import time

cache = {}
CACHE_TTL = 300  # 5 minutes

def get_jobs(api_key):
    if "jobs" in cache and time.time() - cache["jobs"]["time"] < CACHE_TTL:
        return cache["jobs"]["data"]

    response = requests.get(
        "https://fsmnavigator.com/api/v1/jobs",
        headers={"X-API-Key": api_key}
    )
    data = response.json()
    cache["jobs"] = {"data": data, "time": time.time()}
    return data

Use exponential backoff

When you receive a 429 response, wait the time indicated by Retry-After, then retry with increasing delays:

import time
import requests

def api_request_with_retry(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code != 429:
            return response

        wait = int(response.headers.get("Retry-After", 2 ** attempt))
        time.sleep(wait)

    raise Exception("Max retries exceeded")

Batch where possible

Instead of making individual requests for each record, use list endpoints with filters to retrieve multiple records in a single call.

# Instead of 10 individual GET requests:
curl "https://fsmnavigator.com/api/v1/jobs?status=Pending&per_page=100" \
  -H "X-API-Key: YOUR_API_KEY"

Monitor your usage

Check the X-RateLimit-Remaining header on each response to see how close you are to the limit. Slow down proactively when the remaining count gets low.

Frequently asked questions

What happens to requests that exceed the rate limit?

They receive HTTP 429 Too Many Requests. No data is modified or returned — simply wait and retry.

Do rate limits reset at a fixed time?

Rate limits use a rolling time window. The X-RateLimit-Reset header shows when the current window expires.

Can I request higher rate limits?

Contact your account manager. Higher throughput options are available depending on your plan and use case.