Incorrect status code returned from charges endpoint

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”:

  1. 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” } ]
    }

  2. 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
    }

  3. Charges (as you point out) give 404 if there is no data.

  4. 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

  5. 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” } ] }

  6. 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.

1 Like

Hi Mark, thanks for replying. Appreciate it the info!