Request rate limit precedence

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed, GitLab Dedicated

Request rate limits apply before a request reaches a controller or API endpoint. When several general request limits match a request, only one of them counts it. GitLab checks the general limits in a fixed order, and the first enabled limit that matches counts the request. If you disable that limit, the next matching limit counts the request, or no limit does.

The protected paths, Model Context Protocol (MCP) server, and incident management limits count requests separately, in addition to the general limit. Application rate limits also apply separately.

GitLab.com has additional rate limits.

How GitLab selects a rate limit

With the LabKit rate limiter, which is the default, GitLab checks each request in this order:

  1. GitLab skips requests that match an exemption.
  2. The general limiter checks its rules in this order: specialized APIs, the dependency proxy, Git, web, and the general API. The first enabled rule that matches counts the request. Later rules in the general limiter do not count the request.
  3. The protected paths, MCP, and incident management limiters each check the request on their own.
  4. If the request is over any enforced limit, GitLab returns a 429 response. The response body is Retry later by default. To change the response body, see use a custom rate limit response.

The diagram shows how the general limiter selects a rule:

flowchart TD
    accTitle: How the general limiter selects a rate limit
    accDescr: After exemptions, the general limiter checks specialized API, dependency proxy, Git, web, and general API rules in order, and the first enabled rule that matches counts the request.
    Request[Request] --> Exempt{Matches an exemption?}
    Exempt -->|Yes| None[Not counted]
    Exempt -->|No| Specialized{Enabled specialized API, dependency proxy, or Git rule matches?}
    Specialized -->|Yes| Count[Rule counts the request]
    Specialized -->|No| Web{Enabled web rule matches?}
    Web -->|Yes| Count
    Web -->|No| API{Enabled general API rule matches?}
    API -->|Yes| Count
    API -->|No| None
    Count --> Over{Over the limit?}
    Over -->|Yes| Block[429 response]
    Over -->|No| Continue[Request continues]

Exemptions

GitLab checks exemptions before any rate limit. Some exemptions apply to every limiter, and others to specific limiters only:

ExemptionApplies toEffect
Bypass headerEvery limiterSkips requests whose header named by GITLAB_THROTTLE_BYPASS_HEADER has the value 1.
User allowlistEvery limiterSkips users listed in GITLAB_THROTTLE_USER_ALLOWLIST. Does not skip deploy tokens.
Internal API, health checks, and container registry eventsGeneral, protected-path, and per-project Git limitersSkips unauthenticated requests under /api/v<version>/internal/, /-/health, /-/liveness, /-/readiness, /-/metrics, and /api/v<version>/container_registry_event/.
Virtual registries and verified Geo requestsGeneral, protected-path, and per-project Git limiters, in GitLab Enterprise EditionSkips unauthenticated virtual registry requests and verified Geo requests with no user or deploy token.
Runner jobs APIGeneral limiterSkips requests under /api/v<version>/jobs/ that authenticate with a CI/CD job token.

To configure per-project Git limits, see override rate limits for a project.

Request types

GitLab uses the request path, the authentication, and the cross-site request forgery (CSRF) token to select a rule. The path excludes any relative URL prefix for the instance.

TypePathsExamplesCounted by
Git Large File Storage (LFS)Paths under .git/info/lfs/ or .git/gitlab-lfs/, such as the batch API, locks, and object transfers under gitlab-lfs/objects/./<namespace>/<project>.git/info/lfs/objects/batch, /<namespace>/<project>.git/info/lfs/locks, /<namespace>/<project>.git/gitlab-lfs/objects/<oid>Authenticated: Git LFS, or authenticated web if the Git LFS limit is disabled. Unauthenticated: unauthenticated Git HTTP.
Git HTTPRepository paths that Git clients use over HTTP. See the list after this table./<namespace>/<project>.git/info/refs, /<namespace>/<project>/info/refsAuthenticated Git HTTP or unauthenticated Git HTTP.
APIPaths that start with /api/ or contain /oauth/./api/v4/projects, /oauth/tokenA specialized API limit, or the general API limit.
WebAll other paths, except health check paths./<namespace>/<project>Web limit.

A path is a Git HTTP path when it:

  • Ends in .git.
  • Has /info/refs, /git-upload-pack, /git-receive-pack, /ssh-upload-pack, or /ssh-receive-pack after .git.
  • Ends in /info/refs without .git.
  • Is under .git/info/lfs/ or .git/gitlab-lfs/objects/. These paths are also Git LFS paths, and the authenticated Git HTTP limit excludes them.

Each request also has one authentication type:

AuthenticationDefinitionCounted for each
AuthenticatedGitLab resolves a user or deploy token for the request.User or deploy token
UnauthenticatedNo user, deploy token, or runner authenticates the request.IP address
RunnerGitLab resolves a runner instead of a user or deploy token, for example for /api/v4/jobs/request.None. No general limit counts the request.

Frontend API requests

The GitLab frontend sends API requests with the CSRF token of the browser session in the X-CSRF-Token header. Browser sessions of visitors who are not signed in also have a CSRF token. GitLab treats an API request with a valid CSRF token as web traffic, whether or not the request is authenticated:

  • A specialized API limit counts the request if one matches.
  • Otherwise, the web limit counts the request.
  • The general API limit never counts the request, even when the web limit is disabled.

The diagram shows how GitLab classifies common paths:

flowchart TD
    accTitle: Common request path classification
    accDescr: LFS paths qualify for the LFS limit before other Git HTTP paths, and a valid CSRF token excludes requests from the general API limit.
    Path[Request path] --> LFS{Path under .git/info/lfs/ or .git/gitlab-lfs/?}
    LFS -->|Yes| LFSType[Git LFS]
    LFS -->|No| Git{Path matches Git HTTP?}
    Git -->|Yes| GitType[Git HTTP, not LFS]
    Git -->|No| APIPath{Path starts with /api/ or contains /oauth/?}
    APIPath -->|No| WebType[Web]
    APIPath -->|Yes| Frontend{Valid CSRF token?}
    Frontend -->|Yes| FrontendType[Web unless a specialized API rule applies]
    Frontend -->|No| APIType[API]

Order of general rate limits

The general limiter, rack_request, checks these rules from top to bottom. Each rule applies only when you enable its setting.

Authenticated rules count requests for each user or deploy token, even when the setting label mentions only users.

The last column shows which limit counts the request when you disable the rule. That limit must also be enabled. For a specialized API request with a valid CSRF token, the next limit is web instead of API.

OrderRate limitApplies toCounted for eachIf disabled, counted by
1Package registry rate limits: Enable unauthenticated API request rate limit, throttle_unauthenticated_packages_apiUnauthenticated requests to covered package API endpoints, such as /api/v4/projects/<id>/packages/npm/. Not all package API endpoints use this limit.IP addressUnauthenticated API.
2Package registry rate limits: Enable authenticated API request rate limit, throttle_authenticated_packages_apiAuthenticated requests to covered package API endpoints.User or deploy tokenAuthenticated API.
3Enable authenticated dependency proxy request rate limit, throttle_authenticated_dependency_proxyAuthenticated container manifest and blob requests under /v2/<group>/dependency_proxy/containers/.User or deploy tokenAuthenticated web.
4Files API rate limits: Enable unauthenticated API request rate limit, throttle_unauthenticated_files_apiUnauthenticated requests under /api/v<version>/projects/<id>/repository/files/ with a file path.IP addressUnauthenticated API.
5Files API rate limits: Enable authenticated API request rate limit, throttle_authenticated_files_apiAuthenticated requests under /api/v<version>/projects/<id>/repository/files/ with a file path.User or deploy tokenAuthenticated API.
6Deprecated API rate limits: Enable unauthenticated API request rate limit, throttle_unauthenticated_deprecated_apiUnauthenticated requests to /api/v<version>/groups/<id> with with_projects absent, blank, or true.IP addressUnauthenticated API.
7Deprecated API rate limits: Enable authenticated API request rate limit, throttle_authenticated_deprecated_apiAuthenticated requests to /api/v<version>/groups/<id> with with_projects absent, blank, or true.User or deploy tokenAuthenticated API.
8Enable authenticated Git LFS request rate limit, throttle_authenticated_git_lfsAuthenticated Git LFS requests.User or deploy tokenAuthenticated web.
9Enable authenticated Git HTTP request rate limit, throttle_authenticated_git_httpAuthenticated Git HTTP requests, except LFS.User or deploy tokenNone, not authenticated web.
10Enable unauthenticated Git HTTP request rate limit, throttle_unauthenticated_git_httpUnauthenticated Git HTTP requests, including LFS batch, locks, and object transfers under gitlab-lfs/objects/.IP addressNone, not unauthenticated web.
11Enable unauthenticated web request rate limit, throttle_unauthenticated_webUnauthenticated web and frontend API requests. Excludes Git HTTP paths, even when the Git HTTP limits are disabled.IP addressNone.
12Enable authenticated web request rate limit, throttle_authenticated_webAuthenticated web and frontend API requests. Excludes Git HTTP paths except LFS, even when the Git HTTP limits are disabled.User or deploy tokenNone.
13Enable unauthenticated API request rate limit, throttle_unauthenticated_apiUnauthenticated API requests with no valid CSRF token that no earlier rule counted.IP addressNone.
14Enable authenticated API request rate limit, throttle_authenticated_apiAuthenticated API requests with no valid CSRF token that no earlier rule counted.User or deploy tokenNone.

Limits that count separately

These limiters count a request in addition to the general limiter. Disabling one of them does not change which general limit counts the request. Each protected path rule has its own counter, even though the rules share one configuration.

LimiterRate limitApplies toCounted for each
rack_request_protected_pathsEnable rate limiting for requests to the specified pathsPOST requests to a prefix in Paths with rate limiting for POST requests, or GET requests to a prefix in Paths with rate limiting for GET requests.IP address for unauthenticated requests, or user or deploy token for authenticated requests.
rack_request_mcpEnable authenticated MCP server request rate limit, throttle_authenticated_mcpAuthenticated requests to /api/v<version>/mcp or paths below that endpoint, regardless of the HTTP method or body.User or deploy token
rack_request_incident_managementEnable incident management inbound alert limit, throttle_incident_management_notification_webPaths that contain alerts/notify, except API and health check paths, in GitLab Enterprise Edition.Request path

Configuration examples

These examples assume the LabKit rate limiter and no exemption. API requests in the examples have no valid CSRF token. All limits not listed in the second column are disabled.

RequestLimits enabledCounted by
Authenticated Git LFSGit LFS and authenticated webGit LFS only.
Authenticated Git LFSAuthenticated web onlyAuthenticated web.
Authenticated Git LFSNoneNone.
Authenticated Git HTTP, not LFSAuthenticated Git HTTP and authenticated webAuthenticated Git HTTP only.
Authenticated Git HTTP, not LFSAuthenticated web onlyNone.
Unauthenticated Git HTTP, including LFS batch, locks, and object transfersUnauthenticated Git HTTP and unauthenticated webUnauthenticated Git HTTP only, for each IP address.
Unauthenticated Git HTTP, including /<namespace>/<project>/info/refsUnauthenticated web onlyNone.
First unauthenticated attempt of a Git HTTP operationUnauthenticated Git HTTPUnauthenticated Git HTTP, for each IP address.
Covered packages API, files API, or deprecated API requestSpecialized API limit and general API limit with the same authenticationSpecialized API limit only.
Covered packages API, files API, or deprecated API requestGeneral API limit with the same authentication onlyGeneral API limit.
Authenticated MCP API requestAuthenticated API and MCPBoth limits.
GET or POST request to a protected pathProtected paths and the applicable general limitBoth limits, with separate counters.

Dry run mode

In dry run mode, an enabled limit counts requests but does not block them. The limit still stops the check for the requests it matches, so later rules in the general limiter do not count them. As a result, no general limit blocks these requests. For example, with throttle_authenticated_git_lfs in dry run mode, LFS requests do not count against the authenticated web limit.

For configuration and the required Puma restart, see try out throttles before enforcement.

Rack::Attack fallback

The first-match behavior applies only when all six LabKit feature flags are enabled, which is the default:

  • rate_limiter_use_labkit_rack_cohort_1 and rate_limiter_use_labkit_rack_cohort_1_enforce
  • rate_limiter_use_labkit_rack_cohort_2 and rate_limiter_use_labkit_rack_cohort_2_enforce
  • rate_limiter_use_labkit_rack_cohort_3 and rate_limiter_use_labkit_rack_cohort_3_enforce

If any of these flags is disabled, Rack::Attack also checks the requests that LabKit passes through. Rack::Attack does not use rule order, so one request can count against several general limits. For example, a frontend API request to a specialized API path can count twice. When both limits are enabled, the request counts against the specialized limit and the web limit.

Troubleshooting

Identify the rate limit that counted or blocked a request

To identify the rule and the counter:

  1. Check the RateLimit-Name response header, for example throttle_authenticated_git_http. LabKit and Rack::Attack both set this header on blocked requests. For the quota and retry headers, see response headers.

  2. In GitLab 19.5 and later, check rate_limit_state in production_json.log or api_json.log. This field names the LabKit rule that counted the request, even when the request was below the limit. For example:

    json
    ["rack_request:authenticated_git_lfs:allow","rack_request:authenticated_git_lfs_claim:skip"]

    Blocked requests do not reach the application, so these logs have no entry for them. For the field definition, see request log fields.

  3. In GitLab 19.5 and later, for requests that LabKit blocked, check auth_json.log for Rate_Limit_Block messages. GitLab does not log every blocked request. For examples, see Rate_Limit_Block messages.

  4. If the Rack::Attack fallback applies, check auth_json.log for Rack_Attack messages with status: 429. The matched field names the throttle that blocked the request.

To monitor LabKit rule results across requests, use the gitlab_labkit_rate_limiter_rule_evaluations_total metric in GitLab 19.4 and later, or gitlab_labkit_rate_limiter_calls_total in GitLab 19.3.

Git LFS requests blocked by an unexpected rate limit

An LFS request can receive RateLimit-Name: throttle_authenticated_web when the Git LFS limit is disabled. The request then shares the authenticated web limit with all other web requests from the same user or deploy token. To give LFS its own limit, enable the Git LFS rate limit.

Git operations blocked by the unauthenticated Git HTTP rate limit

A Git HTTP client can send a request without credentials before it sends a request with credentials. The first request counts against the unauthenticated Git HTTP limit for that IP address. CI/CD jobs behind the same network address translation (NAT) gateway share that counter. To resolve this problem, raise the unauthenticated Git HTTP rate limit.

Git HTTP requests not rate limited

The authenticated web limit excludes Git HTTP paths except LFS, even when the Git HTTP limit is disabled. If only the authenticated web limit is enabled, those Git HTTP requests have no request rate limit. To apply a limit, enable the authenticated Git HTTP rate limit.