Improve error message when using an API key in the wrong shard.

[TroyLaurin]

Currently when using an API key in the wrong shard you get a generic "401 Unauthorized" response. It would aid discoverability for new developers if the error message could be updated to something like "401 Unauthorized - wrong shard".

[metabren]

I think the issue with this is that there's no way to know an API key is valid on another shard (without checking every other shard — which defeats the purpose of sharding). An authorised API key to one shard looks unauthorised to another. A made-up API key looks unauthorised on both.

(edit: not speaking for Cliniko here, just guessing)

[hagen]

Hi @TroyLaurin 👋 thanks for the query.
Cheers for jumping in there @metabren - that's spot on. Shards don't know about each other by design. For a shard to know an API key belongs to another shard, that shard would need to query every other shard prior to completing the API request. Your one http request to Cliniko would wait on N http requests Cliniko-to-Cliniko on the backend. Inter-region requests also have a distance latency penalty.
All API keys have their shard appended to them to make it clear where that API key may be used.

Unfortunately, I don't think we'll be making any changes for shard-specific errors. If you think our documentation could be clearer though, please let us know.

Cheers!

[TroyLaurin]

I find that the documentation is clear if you know it's there, but when I'm not the primary developer who wrote the code and I'm getting "Unauthorized" responses setting up a new practice I didn't think to scan the entire documentation, I just assumed that the API key had been copied incorrectly and rescheduled the install.

To be clear, I'm not asking to know whether the API key is authorized in some other shard, I was just asking for the error message to be clearer if the API key will never be authorized in the current shard. This would be a single substring test on invalid API keys and add microseconds to invalid requests, with no inter-shard communication.

For what it's worth, we now have the correct code and this change will have no benefit for us, but it might help new developers trying to use your API. Feel free to close if it remains wontfix.

[metabren]

Hey @TroyLaurin looks like I misunderstood your original post — sorry! Thanks for explaining further. I think something like that would help future developers running into this issue.