I will add this to the current milestone as it is a dependency for improving rate limiting on Cloud

I am not too sure if I am on the right track here. I think to prepend this before the line. Would that works?

   // load rate limit page if status code 429
        if (http_response_code() === 429) {
            $view = new view('@API/rateLimit');
            return $view->render();
        }

I was expecting more likely something in AjaxHelper.ts where it currently handles all errors with 'Something went wrong' (except 504 gets a different message). Maybe worth running this by @bx80 to devise a plan here

@JasonMortonNZ just a question on the UI changes, currently the UI shows this error message for the API endpoints

• I could update this message to mention rate-limiting as a possible cause. This will be a simple change.
• I could detect 429 as a response code and show different messages.

I suggest using option 2. I can use this text there.

I would suggest to maybe not directly implement any screen or custom message in Matomo itself, as it's quite cloud related only.
It might make more sense to trigger a javascript event whenever a request fails with an unexpected response code.
That way the cloud plugin could hook into that event and display a custom message.
This would later also allow to handle any other response code, we might need to introduce on cloud

I could detect 429 as a response code and show different messages.

This would be ideal @peterhashair . We would want to handle the 429 error directly in core and then show a message. However, the message will need to be different so it works for regular On-Premise users too. The Cloud team will then maybe want to overwrite the message/translation.

I would suggest to maybe not directly implement any screen or custom message in Matomo itself, as it's quite cloud related only.

The idea was to have this in core so that other On-Premise users can benefit from this as well as some would already have some rate limiting configured and as always we would then ideally also document this behaviour in an FAQ so making it more clear when others set it up in the future.