Include a Link to the Documentation in Rack Attack Rate Limit Responses

Description

Problem: When a user receives a rate-limit error, they may not have knowledge of the current rate limit setting for the API they are calling or how to leverage the retry-after header to know when to safely retry the request.

Goal: Help users better understand the current rate limit settings and how to deal with a rate limit error

Options

• Allow self-managed administrators to customize the rate limit response so that they can return a helpful documentation page explaining how their users can deal with rate limits

or

• Include a link to the GitLab rate limit documentation (https://docs.gitlab.com/ee/security/rate_limits.html) in the 429 header response in RackAttack. If we go with this option we may need to update the rate limit documentation to describe how a user can determine rate limit settings for the API they're calling and add a section on how a user can parse the retry-after header to safely retry the request.

Other Information

See further discussion here: gitlab-com/gl-infra&341 (comment 466028803)