Five beliefs cause most rate limit surprises in CI: that limits are per pipeline, that signing in removes them, that any pull counts the same, that fast retries get through, and that a bigger fleet needs more registry access. Each is wrong or incomplete, and the vendor documentation shows why.
Myth 1: "The limit is per pipeline"
Fact. Docker's documentation counts unauthenticated pulls per IPv4 address or IPv6 /64 subnet. MDN adds that rate limiting restrictions may be server wide or per resource. Neither is per pipeline. If many pipelines leave through one gateway, they share a bucket. Detail in why CI jobs hit pull rate limits on a shared runner IP.
Myth 2: "If we sign in, there is no limit"
Fact. Docker's table lists a pull rate limit per 6 hours that depends on account type. Unauthenticated users get 100 per address. Authenticated personal accounts get 200. Pro, Team and Business accounts are listed as unlimited, subject to fair use. So signing in raises the allowance, and what you get depends on the plan. Read the table for your plan, and re-read it when you plan fleet growth, because limits change. See Docker Hub rate limit policy changes.
Myth 3: "Every docker pull costs one pull"
Fact. Docker's definition says a pull includes both a version check and any download that results. Version checks, which verify that an image or tag exists without downloading it, do not count towards usage. A normal image is one pull for a single manifest, but a multi-architecture image counts as one pull per architecture. A job that pulls the same image for two architectures uses two.
Myth 4: "Retry fast and one will get through"
Fact. A 429 means too many requests in a given time. MDN says a Retry-After header may be included to say how long to wait. Retrying immediately adds to the count that caused the limit. A fleet doing it together creates the pattern in retry storms. Wait at least the Retry-After value if one is sent, add jitter, and cap attempts. MDN also notes that client support for the header is inconsistent, so you may have to read it in your own script.
Myth 5: "A bigger fleet means we should request a higher limit"
Fact. More runners usually means more repeat pulls of the same images. The cheaper fix is to stop pulling the same thing many times:
- Run a pull-through cache so many jobs share one upstream pull. See mirror Docker Hub images with a pull-through cache.
- Copy the base images you depend on into your own registry.
- Reuse layers within a runner where runners persist. The trade-offs are in ephemeral vs persistent CI runners.
A higher limit with the same waste only moves the problem later.
A one page summary
| Belief | Reality |
|---|---|
| Limit is per pipeline | Per address or per account, shared by your fleet |
| Signing in removes it | Raises it, depending on plan |
| Every pull counts once | Version checks do not count, multi-arch counts per architecture |
| Retry quickly | Wait, honour Retry-After, add jitter |
| Ask for more | Cache and copy first |
What to do this week
- Find your 429s and group them by image and by hour.
- Check which account, if any, your runners authenticate as.
- List the base images your pipelines pull and how often.
- Decide whether a pull-through cache or a copy into your own registry fits better.
Where Safeguard fits
Once your base images are in one place, Safeguard's container image scanning and SBOM show what each contains and which findings are reachable. You can start with a free scan at gold.safeguard.sh/scan.
Quick check
Does a pull of a multi-architecture image count once?
Docker's documentation says it counts as one pull for each architecture, so pulling several architectures uses several pulls.
What should a script do on a 429?
Wait at least the Retry-After value if present, add random jitter, and limit the number of attempts. Do not retry immediately.
Sources
Last reviewed: 19 October 2026.
