Rate limits

Your monthly quota

Every key has a monthly request allowance that resets at the start of each calendar month (UTC). There is no per-second throttle — the monthly allowance is the only per-key limit.

Every API call — entity profile, risk signals, or search — counts as one request against the key's quota, regardless of how many sources were consulted to serve it. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers so you can track consumption programmatically.

Successful requests consume quota. Failed requests usually do not: if the API could not serve a response because of an upstream problem on our side, the request is refunded and does not count against your monthly allowance. The only failure that still consumes quota is 429 rate_limit_exceeded itself.

When a key exhausts its allowance the API returns 429 with rate_limit_exceeded and a Retry-After header (seconds until the monthly reset). Quota is per user: if you regenerate your key, usage carries over.

The upstream budget — and why free sheds first

Companies House caps every integrator at 600 requests per rolling 5 minutes per API key. Rotuli uses one shared Companies House key for the whole platform, so that 600/5min is a global ceiling on everyone's cold lookups combined — not a per-customer limit. To stay under it, the API runs a proactive token-bucket limiter (budget) in front of every outbound Companies House call and sheds requests when the bucket is exhausted rather than queueing them.

The bucket is deliberately tuned below the Companies House hard limit and is graded by tier: as it drains, lower tiers are shed first to preserve capacity for paid tiers. In practice that means during sustained upstream pressure a Free key is more likely to see upstream_capacity than an Enterprise key making the same call.

Shedding is graceful wherever possible:

• If the core Companies House fetch is shed, the request fails with 429 upstream_capacity and a short Retry-After (seconds, while the bucket refills — not the monthly reset). This failure is refunded: it does not consume your monthly quota.
• If only a secondary source is shed, you get a partial 200 with that source recorded in sources_failed and any affected risk flags marked indeterminate — never a silently lower score. Because a response was served, this still consumes quota.
• Search returns 503 upstream_unavailable instead — the same condition, surfaced differently per endpoint. This failure is also refunded and does not consume quota.

upstream_capacity vs rate_limit_exceeded

Both return 429 with a Retry-After header, but they are unrelated:

• rate_limit_exceeded — yourkey's monthly quota is spent. Only you are affected. This consumes quota (the request that tripped the limit counts). Retry after the monthly reset, or upgrade your tier.
• upstream_capacity — the shared Companies House registry is saturated. Everyone is affected, it has nothing to do with your usage, the failed request is refunded and does not consume your monthly quota, and a retry after the indicated interval (seconds) will normally succeed.

See error codes for the full table.

Feature availability per tier

Quotas aside, some features are tier-gated. The /entity/{company_number}/risk endpoint requires a Growth or Enterprise key — on the Free tier it returns 403 risk_tier_required. The full entity endpoint embeds risk_signals only for paid keys too.

Checking usage and upgrading

Current usage is shown in the dashboard under Usage. To raise your limit, switch tiers on the pricing page or via dashboard → Billing. Tier changes apply in place to your existing key — your key never rotates when you upgrade or downgrade.