# Troubleshooting Companies House Lookup

What the common errors in D2K Companies House Lookup mean and what to do about
them. Each heading quotes the start of the message as Business Central shows
it. For the full list of messages, word for word, see [Messages and what to do about them](https://docs.d2k.uk/companies-house-lookup/companies-house-messages).

## "Companies House API key is not configured"

No API key has been saved for this company. Open [Companies House Setup](https://docs.d2k.uk/companies-house-lookup/companies-house-setup) and save one. The key is per company, so a new
company in the same tenant needs its own.

## "Companies House API key is invalid" or "Companies House rejected the API key"

The first appears during a lookup, the second when you choose **Test
Connection** or **Save API Key**. Both mean the same thing. The key is wrong, has been revoked, or is a streaming key rather than a REST
API key. Create a fresh REST key at
<https://developer.company-information.service.gov.uk/> and save it again.

**Test Connection** on the setup page checks the stored key at any time and
updates **Last Authenticated** when it works.

## "Companies House requests are throttled locally"

The app stopped itself before Companies House did. The free key allows 600
requests every five minutes for your whole tenant, and the app counts its own
usage so that you get a clear message instead of a rejection.

Wait a few minutes and try again. If it happens regularly:

- Lengthen the cache lifetimes on [Companies House Setup](https://docs.d2k.uk/companies-house-lookup/companies-house-setup), so repeat lookups are served locally.
- Match records in smaller batches - each unmatched record is one call.
- Reduce the number of watched companies, or check whether several people are
  refreshing large selections at the same time.

## "Companies House service is temporarily unavailable" or "Companies House did not respond"

The register returned a server error or could not be reached. The app retries
automatically, backing off between attempts, and serves what it already has
where it can. If it persists, check
<https://developer.company-information.service.gov.uk/> for service status.

## "Could not reach Companies House"

**Test Connection** shows this when the call never left Business Central. The
usual cause is a sandbox environment that was copied from production: outbound
calls from apps are switched off in the copy. An administrator opens
**Extension Management**, selects D2K Companies House Lookup, chooses
**Configure** and turns on **Allow HttpClient Requests**.

## "Companies House is rate-limited"

Companies House itself refused the call because the limit of 600 requests
every five minutes was reached. The app normally stops before this happens, so
this message usually means something else is using the same API key. Wait a
few minutes and try again, and give each system its own key.

## "The Company Registration Number is not in a recognised Companies House format"

The app expects a UK registration number: eight characters, optionally with a
regional prefix such as `SC`, `NI` or `OC`. Spaces are ignored and short
numbers are padded with leading zeros. Anything else is rejected before a call
is made.

If you do not know the number, search by name instead - see [Look up a company](https://docs.d2k.uk/companies-house-lookup/look-up-a-company).

## "No company found with CRN"

The number has the right format but the register has no company with it.
Check the number at
<https://find-and-update.company-information.service.gov.uk/>. Common causes:

- the number belongs to a company registered outside the UK, which this
  register does not hold,
- leading zeros were lost in a spreadsheet - the app pads them back, but only
  if what remains is otherwise valid,
- the number is a VAT number or a charity number rather than a company number.

## The background poll has stopped

A notification appears on the Role Centre and the watch list when the hourly
job has not run when it should have. It begins "The Companies House filing
poll appears to be stalled".

The usual cause is the **licence of the user who set the job queue entry to
Ready**. The job runs as that user; if their licence is removed or reassigned,
polling stops. Check the job queue entry, set it to Ready as a user whose
licence will stay, and keep an eye on **Last Polled At** on the watch list.

Also check that the job queue itself is running in this environment, and that
the user has permission to read and write the app's tables.

Two actions on **Companies House Filing Watches** help here. **Schedule hourly
poll** creates the job queue entry again if it has gone, and **Poll now**
checks every enabled watch straight away without waiting for the job. See
[Filing watches](https://docs.d2k.uk/companies-house-lookup/filing-watches).

## Document downloads do not work

- **Sandbox Mode is on.** The Companies House sandbox does not serve filed
  documents. Turn it off on [Companies House Setup](https://docs.d2k.uk/companies-house-lookup/companies-house-setup).
- **The filing has no document.** Not every register entry has one. The
  **Document** column on the filings list tells you before you click.
- **An old filing shows no document.** Filings recorded before your version
  supported downloads carry no document link. Choose **Refresh** on the
  filings view for that company to fill them in.

## Seeing what the app has actually called

**Companies House API Call Log** records every call. Open it from the search.
It needs the **D2KL Admin** permission set.

| Column | Meaning |
|---|---|
| **Called At** | The date and time of the call |
| **Endpoint** | The Companies House address that was called, with the registration number and search words left out |
| **Company Registration Number** | The company the call was about |
| **HTTP Status** | The status Companies House returned: 200 is success, 401 a rejected key, 404 not found, 429 rate limited |
| **Response Time ms** | How long the call took, in milliseconds |
| **From Cache** | Ticked when the answer came from the stored snapshot and no call was made to Companies House |
| **Error Message** | What went wrong, when the call failed |
| **Called By** | The user who started the call |

Registration numbers and search terms never appear in the logged endpoint, so
the log can be shared with support without carrying customer data. The log is
kept under the standard **Retention Policies**, so an administrator controls
how long it lives.

## Getting help

Email **support@d2k.uk** with what you were doing, the exact message, and - if
you can - the relevant rows from the API Call Log.

---
Source: https://docs.d2k.uk/companies-house-lookup/companies-house-troubleshooting
Last updated: 2026-10-04