When using the charges endpoint a 404 is returned when there are no charges for a company instead of a 200.
The 404 response is also missing from the documentation for the endpoint here: https://developer.companieshouse.gov.uk/api/docs/company/company_number/charges/getChargeList.html
Agreed. The issues here are:
- The documentation doesnât match what the API produces.
- The documentation isnât clear about what circumstances produce specific âerrorâ responses.
Some examples (using cUrl - the -I flag just returns the header instead of the response body to show that):
curl -u{myAPIKEY}: "https://api.companieshouse.gov.uk/company/00229606/charges"
⌠returns the charge list, since that exists for the company.
curl -u{myAPIKEY}: -I "https://api.companieshouse.gov.uk/company/05003861/charges"
âŚreturns âHTTP/1.1 404 Not Foundâ in the header since there are no charges recorded.
(Just search on Beta to find companies with / without charges).
Using a completely non-existent company number:
curl -u{myAPIKEY}: -I "https://api.companieshouse.gov.uk/company/99990303/charges"
âŚreturns âHTTP/1.1 404 Not Foundâ.
Ignoring the docs for the moment (which mention HTTP returns of 200, 400 and 401) the API behaviour appears to be:
- If there are charges, you get code 200 and a chargelist resource.
- If the company doesnât have charges or the company number doesnât exist in the API dataset, you get a 404.
Obviously you could test to see if the company has charges by requesting the company profile first and checking the âhas_chargesâ member. (Note this doesnât mean âhas active chargesâ but âhas / had charges, fullfilled or notâ).
Someone from CH could maybe make a note on the documentation that it may differ from the API in numerous areas, but if they were going to do that I guess they could just go ahead and update the docsâŚ
Veering away from original question - across the API queries are inconsistent in their behaviour when data is missing / query âdoesnât applyâ:
-
Company profile request where company number doesnât exist or company was removed from CH API dataset:
curl -u{myAPI KEY}: âhttps://api.companieshouse.gov.uk/company/05207708â
{âerrorsâ:
[ { âtypeâ : âch:serviceâ, âerrorâ : âcompany-profile-not-foundâ } ]
} -
Filing history may return a blank data set (with status âfiling history availableâ!)
curl -u{myAPI KEY}: âhttps://api.companieshouse.gov.uk/company/05207708/filing-historyâ
{
âstart_indexâ : 0, âfiling_history_statusâ : âfiling-history-availableâ,
âitemsâ : [ ], âtotal_countâ : 0, âitems_per_pageâ : 25
} -
Charges (as you point out) give 404 if there is no data.
-
Insolvency history doesnât seem to give 404 but instead you may get a ânullâ response if there isnât one e.g.:
curl -u{myAPI KEY}: âhttps://api.companieshouse.gov.uk/company/05003861/insolvencyâ
null -
PSCs return an error object:
curl -u{myAPI KEY}: âhttps://api.companieshouse.gov.uk/company/03888792/persons-with-significant-controlâ
{ âerrorsâ : [ { âtypeâ : âch:serviceâ, âerrorâ : âcompany-psc-not-foundâ } ] } -
Registers (I have never used this or found any example with data here, but presumably someone does):
curl -u{myAPIKEY}: -I âhttps://api.companieshouse.gov.uk/company/05003861/registersâ
HTTP/1.1 404 Not Found
âŚ
I realise this is quite an old thread now, but Iâve got the same question - with the context of this endpoint in particular:
âGET /company/{company_number}/chargesâ
Can we safely interpret a 404 response as there being NO charges? From the previous messages above, it doesnât sound like a guarantee that this is the case.
Could we please get someone from Companies House to comment on:
- how to interpret a 404 for this endpoint?
- what response would indicate âno charges existâ?
The âlinks. chargesâ section in the company profile is the most reliable indicator of whether charges exist.
The Beta site uses this âlinksâ section to determine what âtabsâ to display.
Hi Mark, thanks for replying. Appreciate it the info!