404 Not Found error when querying PyPI JSON API for package metadata

Question

GoalDevelop a client that can gracefully handle cancellation and timeout scenarios when retrieving package metadata from the PyPI JSON API.Constraints and UncertaintyThe API returns a 404 Not Found with a JSON body containing "Not found" for non‑existent packages, and a 429 Too many requests when the rate limit (~60 req/min) is exceeded. No timeout header or cancellation signal is exposed; clients must rely on their HTTP library’s timeout or cancellation mechanisms. The lack of a documented cancellation protocol is an open design decision that may be addressed in future releases.Unresolved QuestionsDoes PyPI provide any recommended pattern for canceling in‑progress requests, or is it entirely left to client libraries?What is the expected behavior when a client times out before receiving a response—should the client treat it as a transient error or a permanent failure?Will future PyPI releases introduce a timeout header or cancellation token to support graceful shutdown of long‑running requests?

Tasadduq Burney · Answer

Confirmed facts
PyPI’s JSON API returns HTTP 404 with a JSON body containing “Not found” (or {"message":"Not found"}) when the requested package name does not exist. It returns HTTP 429 when the ~60 requests/min limit is exceeded. No timeout or cancellation headers are exposed.
Likely explanation
A 404 usually means the package name is misspelled, uses the wrong case, contains hyphens/underscores incorrectly, or the package was never published or has been removed. The API does not distinguish transient vs permanent errors for 404.
Steps to handle 404, timeout and cancellation

Parse the response status.

If status === 404 → treat as permanent failure. Log the missing package, optionally surface a user‑friendly message, and do **not** retry.
If status === 429 → apply exponential back‑off with jitter (e.g., start at 1 s, double each attempt) and retry.
If status === 200 → process the JSON payload normally.

Configure client‑side timeout and cancellation.

Set a reasonable timeout (e.g., 5–10 s) using your HTTP library’s timeout mechanism (requests.timeout, aiohttp.ClientTimeout, fetch with AbortController, etc.).
Wrap the request in a cancellation token or abort signal so the operation can be stopped on user‑initiated cancellation.
On a timeout or abort error, treat it as a **transient** error: retry after back‑off, respecting the same 429‑back‑off logic.

Optional diagnostics – ask: Is the package known to exist in the public index? If you receive a 404 for a package you expect to be present, verify network/proxy or mirror issues before treating it as permanent.

Verification (quick sanity check)
# curl example for a non‑existent package
curl -s -o /dev/null -w "%{http_code}
" https://pypi.org/pypi/thispackagedoesnotexist123/json
# Expected: 404

# curl example with timeout to see transient behavior
curl --max-time 1 https://pypi.org/pypi/requests/json 2>&1 | head -n 1
# Expected: timeout error (operation timed out)

404 Not Found error when querying PyPI JSON API for package metadata

Goal

Constraints and Uncertainty

Unresolved Questions

1 answer

Confirmed facts

Likely explanation

Steps to handle 404, timeout and cancellation

Verification (quick sanity check)

Your perspective belongs here.

0 question comments