It sounds like you’re finding this quite frustrating. From what you’ve reported - using curl - the most likely issue would be that you’ve not got the API key in the correct place or are missing something here. Assuming you’re using the example line from the documentation:
… that does indeed work (I just did this). What seems to cause the most trouble is misunderstandings of http Basic authentication and what you need to do with the API key to make that work with your programming language / tool.
For doing this with curl the key parts are:
You need your own API key (not a stream key…) which you got when you registered your app. That is the http Basic user name.
There is no password. So check that (as in the example) you’ve got your API key (username) followed by a colon then a space (so no password) then the next bit of the curl command. (You don’t actually need the -XGET bit).
If that still fails, next most likely is there is something amiss with the app registration. We joined up some time ago and things have changed since then - including the documentation (which used to be a bit longer…). It looks like you may now have to choose an “Application Environment” setting as mentioned here:
e.g. in that case the issue was solved by setting:
Application environment - test
Application environment - live
There does seem to be a current bug which may relate to this but that was only affecting someone who had set up a long time ago:
If you’re sure all that is set up correctly but you’re still stuck then yes - post exactly what you did (edit out your api key though) and ping Companies House…
Obviously there are lots of people using this service. You mention that this “seems to be a very well-reported error” - so you’re clearly searching this forum. Most of the issues we have run into have been resolved by doing just that so I would say that this forum is effectively the “resolution documentation” that you describe. I think - though needing some diligence / patience - this makes up for any deficiencies in the official documentation. I agree that certain common pitfalls that people run into could usefully have some specific documentation. There are also places where the official documentation could be improved - but our experience with other APIs (some governmental) shows this is not a bad example.
There are some “non-standard” features of this API but in my experience that is a universal - even with the various attempts to “standardise” REST APIs etc. This is a pretty straightforward one. The only other issue is that things will inherently be “fuzzy” (e.g. missing / outright “invalid”) given the size / time duration of dataset, the fact that it is generated by “the public” themselves and (by law, political will / resource limitations) is not well-validated and the fact that the whole process here is governed not by “technical / data” considerations but by political / legal ones.