Working with rate limits

The absolute rules live in the Rate limits reference. This guide is the how-to.

Read the headers on every response

The engine ships X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on every 2xx. Log them or plumb them into your metrics.

const resp = await fetch(url, { headers });
const remaining = Number(resp.headers.get("X-RateLimit-Remaining"));
if (remaining < 10) metrics.warn("landedfees_ratelimit_close", { remaining });

Batch before you loop

500 individual calc calls sent in a tight loop will 429 immediately (and burn 500 quota entries).
One /v1/calc/bulk call with 500 rows uses one rate-limit slot and one quota entry.
Six /v1/rates calls for a sourcing comparison burn six slots. One /v1/compare call fans out to all 6 origins server-side and uses one slot.

Concurrency ceiling

Cap outbound concurrency at 8 workers per key. At 8 concurrent workers averaging 500 ms per call, sustained throughput is roughly 960 rpm from the calling side, but only 60 rpm from the server side will succeed. The excess simply 429s. Prefer fewer workers with the built-in retry loop.

Multi-key sharding

Rate limits are per key, not per organization. Split workloads by minting one key per workload:

prod-quote-engine for real-time UI quoting.
ci-nightly-audit for the nightly re-run.
data-warehouse-etl for the ETL that pulls rate snapshots.

Each key gets its own 60 rpm bucket. Do not mint keys purely to dodge the limit; the monthly quota is per organization.

Backoff with jitter

The SDKs implement exponential backoff with jitter automatically. If you are rolling your own:

attempt 0: retry-after seconds + rand(100..500) ms
attempt 1: 2s  + rand(100..500) ms
attempt 2: 4s  + rand(100..500) ms
attempt 3: 8s  + rand(100..500) ms
cap at 60s. Give up after attempt 5.

When to ask for higher limits

Ask when:

Your workload genuinely exceeds 60 rpm per key sustained, after moving to bulk and compare endpoints.
You have a burst pattern that a longer window cannot absorb.

Growth and Business ceilings are fixed at 60 rpm per key. Custom ceilings ship on Enterprise contracts. Contact sales.

Getting Started

Core Concepts

API Reference

Guides

Reference

SDKs

Playground

Read the headers on every response

Batch before you loop

Concurrency ceiling

Multi-key sharding

Backoff with jitter

When to ask for higher limits

​Read the headers on every response

​Batch before you loop

​Concurrency ceiling

​Multi-key sharding

​Backoff with jitter

​When to ask for higher limits

Read the headers on every response

Batch before you loop

Concurrency ceiling

Multi-key sharding

Backoff with jitter

When to ask for higher limits