API and developers

API rate limits and error codes (401, 403, 404, 429)

Each API plan has a per-minute and per-day limit, shared by all your keys. What the 400, 401, 403, 404, 429, 500 and 503 responses mean, and what to do about each.

Rate limits

API plan	Per minute	Per day
Free	30	1,000
Starter	60	10,000
Business	200	100,000
Enterprise	Set to your workload	From 500,000

Limits are per account. All your keys share them.
The minute limit resets at the start of each minute. The daily limit resets at midnight UTC.
Every data call counts, whatever the response. Calls to /auth and /billing do not count.
There is no monthly quota and no overage charge. When you reach a limit, requests are refused until it resets.

Every counted response includes these headers, with reset times in Unix seconds:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed per minute
`X-RateLimit-Remaining`	Left this minute
`X-RateLimit-Reset`	When the minute resets
`X-RateLimit-Daily-Limit`	Requests allowed per day
`X-RateLimit-Daily-Remaining`	Left today
`X-RateLimit-Daily-Reset`	When the day resets

Your usage is on the Usage page.

Error responses

Errors come back as JSON with an error message. Many also have a code and a hint.

400: Bad request

A parameter is missing or not valid. details lists each field and what is wrong. Fix the request and try again.

401: Authentication required, or invalid key

Authentication required: no key was sent. Add the Authorization or X-Api-Key header.
Invalid API key format. Keys start with cs_: check you copied the whole key.
Invalid or revoked API key: the key was revoked or regenerated. Use a current key from the API keys page.

403: Forbidden

code: plan_upgrade_required: your plan does not include this endpoint. The response says which plan you need, in required_plan. Upgrade on the billing page. A 403 for this reason does not count against your limits.
Account is disabled: contact support.

404: Not found

Company not found: no company has that number. Company numbers have 8 characters, for example 00445790 or SC123456. We add missing leading zeros for you, so check the letters and digits themselves.
Not found: the address is wrong. Check the path in the documentation.

429: Too many requests

You have reached your per-minute or daily limit. The response has a Retry-After header with the number of seconds to wait, and says which limit you hit in window ("minute" or "day").

What to do:

wait for the Retry-After seconds, then retry;
pace your requests using the X-RateLimit-Remaining header;
for bulk work on Business, look up 100 companies in one request with POST /company/bulk;
if you regularly hit the limit, upgrade your plan.

500: Internal server error

Something went wrong on our side. Retry after a short wait. If it keeps happening, raise a request at Support with the time, the endpoint and the response.

503: Companies House is not responding

code: upstream_unavailable. Some data is fetched live from Companies House. Retry after the Retry-After time, usually 30 seconds.

Last updated 2 October 2026

Still need help? Contact us, or if you have an account, open a support request.