Troubleshooting Companies House Lookup
Last updated
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.
"Companies House API key is not configured"
No API key has been saved for this company. Open 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, 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.
"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.
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.
- 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.