Limits of 409 Conflict as a retry-success signal in PyPI uploads

The Short Answer

No, PyPI's upload API does not expose a documented distinction between an exact-duplicate retry and a conflicting new artifact. A 409 Conflict is returned whenever a file with the same filename already exists for that version, regardless of whether the content hash matches. Interpreting 409 as "success" is only safe if your build pipeline guarantees byte-for-byte reproducibility.

Analysis of the 409 Conflict Signal

In the PyPI legacy upload API, the 409 Conflict response is a blunt instrument. It signals that the server already possesses a file with the requested name for the specified version. Because PyPI prohibits the overwriting of existing releases to ensure package immutability, the server rejects the upload without performing a content-hash comparison to see if the new file is identical to the old one.

The Reproducibility Gap

Tools like Twine treat 409 as a signal to skip the upload, effectively treating it as an idempotent success. This assumption holds only if the local artifact is identical to the server's copy. If your pipeline regenerates a wheel (e.g., due to timestamps, build environment changes, or source modifications) but keeps the same version string, the 409 response will mask the fact that the artifact you intended to upload was rejected in favor of a different, existing version.

Limits of the JSON Simple API

The JSON Simple API allows you to query existing releases and their associated files, but it is insufficient for verifying artifact integrity. While it provides filenames and sizes, it does not provide a server-side checksum (like SHA-256) for the uploaded files. Therefore, you cannot use the Simple API to confirm that a specific hash has been uploaded before deciding to retry.

Recommended Implementation Strategy

To avoid masking build errors or publishing incorrect artifacts, follow these steps:

1. Enforce Reproducible Builds: Use tools like build with environment pinning to ensure that the same source always produces the same byte-for-byte wheel.
2. Pre-flight Version Check: Query the Simple API to check if the version string already exists. If it does, fail the build immediately rather than attempting an upload and relying on the 409 response.
3. Local Hash Verification: If you must retry, calculate the SHA-256 hash of the local artifact and compare it against a locally stored manifest from the previous attempt to ensure the file hasn't changed between retries.

Missing Diagnostic: Are you currently using a deterministic build environment (e.g., pinned pip/setuptools versions and SOURCE_DATE_EPOCH)? If not, the 409 signal should be treated as a failure, not a success.