From fd7b9eb509e94858590848d2df2a6f14931b5f8b Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Sat, 6 Dec 2025 16:09:39 -0800 Subject: [PATCH 1/3] Error responses conform to the :rfc:`9457` format. As per suggestion: https://discuss.python.org/t/pep-694-pypi-upload-api-2-0-round-2/101483/32 --- peps/pep-0694.rst | 45 ++++++++++++++++++++++++++++++--------------- 1 file changed, 30 insertions(+), 15 deletions(-) diff --git a/peps/pep-0694.rst b/peps/pep-0694.rst index 582638654fa..cc1e8c07117 100644 --- a/peps/pep-0694.rst +++ b/peps/pep-0694.rst @@ -84,8 +84,8 @@ In addition, there are a number of major issues with the legacy API: The new upload API proposed in this PEP provides ways to solve all of these problems, either directly or through an extensible approach, allowing servers to implement features such as resumable and parallel uploads. -This upload API this PEP proposes provides better error reporting, a more robust release testing experience, -and atomic and simultaneous publishing of all release artifacts. +This upload API this PEP proposes provides better and more standardized error reporting, a more robust release +testing experience, and atomic and simultaneous publishing of all release artifacts. Legacy API ========== @@ -274,17 +274,26 @@ are determined by the index operator. Errors ------ +Unless otherwise specified, all error (4xx and 5xx) responses from the server **MUST** use the :rfc:`9457` +(Problem Details for HTTP APIs) format. In particular, the server **MUST** use the "Problem Details JSON +Object" defined in :rfc:`Section 3 <9457#section-3>` and **SHOULD** use the ``application/problem+json`` media +type in its responses. + Clients in general should be prepared to handle `HTTP response error status codes -`_ which **MAY** contain payloads of the -the following format: +`_ which **SHOULD** contain payloads like +the following, although note that the details are index-specific, as long as they conform to RFC 9457. By way +of example, PyPI could return the following error body: .. code-block:: json { + "type": "https://docs.pypi.org/api/errors/error-types#invalid-filename", + "status": 400, + "title": "The artifact used an invalid wheel file name format", + "details": "See https://packaging.python.org/en/latest/specifications/binary-distribution-format/", "meta": { "api-version": "2.0" }, - "message": "...", "errors": [ { "source": "...", @@ -293,11 +302,13 @@ the following format: ] } -Besides the standard ``meta`` key, this has the following top level keys: +RFC 9457 defines ``type``, ``status``, ``title``, and ``details``. The ``meta`` and ``errors`` keys are +"extension members", defined in `section 3.2 of RFC 9457 +`_. The index **SHOULD** include these +extension members. -``message`` - A singular message that encapsulates all errors that may have happened on this - request. +``meta`` + The same request/response metadata structe as defined in the :ref:`publishing-session` description. ``errors`` An array of specific errors, each of which contains a ``source`` key, which is a string that @@ -683,14 +694,14 @@ The request looks like: Besides the standard ``meta`` key, the request JSON has the following additional keys: ``filename`` (**required**) - The name of the file being uploaded. The filename **MUST** conform to either the `source - distribution file name specification + The name of the file being uploaded. The filename **MUST** conform to either the `source distribution + file name specification `_ or the `binary distribution file name convention `_. - Indexes **SHOULD** validate these file names at the time of the request, returning a ``400 Bad - Request`` error code, as described in the :ref:`session-errors` section when the file names do - not conform. + Indexes **SHOULD** validate these file names at the time of the request, returning a ``400 Bad Request`` + error code and an RFC 9457 style error body, as described in the :ref:`session-errors` section when the + file names do not conform. ``size`` (**required**) The size in bytes of the file being uploaded. @@ -1094,7 +1105,11 @@ as experience is gained operating Upload 2.0. Change History ============== -* `23-Sep-2025 `__ +* `06-Dec-2025 `__ + + * Error responses conform to the :rfc:`9457` format. + +* `23-Sep-2025 `__ * Remove the ``nonce`` and ``gentoken()`` algorithm. Indexes are now responsible for generating an cryptographically secure session token and obfuscated stage URL (but only if they support From 0ba5fbe2c40db2ae951f9caae14a029fb71a588e Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Sat, 6 Dec 2025 16:14:49 -0800 Subject: [PATCH 2/3] Fix `make lint` --- peps/pep-0694.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/peps/pep-0694.rst b/peps/pep-0694.rst index cc1e8c07117..6f8193f5266 100644 --- a/peps/pep-0694.rst +++ b/peps/pep-0694.rst @@ -303,8 +303,7 @@ of example, PyPI could return the following error body: } RFC 9457 defines ``type``, ``status``, ``title``, and ``details``. The ``meta`` and ``errors`` keys are -"extension members", defined in `section 3.2 of RFC 9457 -`_. The index **SHOULD** include these +"extension members", defined in :rfc:`Section 3.2 <9457#section-3.2>`. The index **SHOULD** include these extension members. ``meta`` From d6ee25ac84bd0546ffc49aa0e3ec777e7f10e6ba Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Sun, 7 Dec 2025 12:21:23 -0800 Subject: [PATCH 3/3] Fix typo --- peps/pep-0694.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0694.rst b/peps/pep-0694.rst index 6f8193f5266..ae2d25a3598 100644 --- a/peps/pep-0694.rst +++ b/peps/pep-0694.rst @@ -307,7 +307,7 @@ RFC 9457 defines ``type``, ``status``, ``title``, and ``details``. The ``meta`` extension members. ``meta`` - The same request/response metadata structe as defined in the :ref:`publishing-session` description. + The same request/response metadata structure as defined in the :ref:`publishing-session` description. ``errors`` An array of specific errors, each of which contains a ``source`` key, which is a string that