Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 69 additions & 0 deletions source/specifications/simple-repository-api.rst
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,74 @@ can be implemented in Python with the ``re`` module::
def normalize(name):
return re.sub(r"[-_.]+", "-", name).lower()


.. _simple-repository-api-error-responses:

Error Responses
---------------

Package indices
~~~~~~~~~~~~~~~

When preparing to send an error response to a requester (e.g., an installer client),
the package index **SHOULD** format its response as an
:rfc:`RFC 9457 Problem Details object <9457#section-3>`.

Implementers should consult :rfc:`9457` for a fully detailed description of the
Problem Details object format. The following is an abbreviated description:

- Each Problem Details object is a JSON (:rfc:`8259`) object.
- Each Problem Details object **MAY** have the following members. All members are optional.

- ``type`` is a JSON string containing a URI reference. It **MAY** be a "locator,"
i.e. an HTTP or HTTPS URI, in which case it **SHOULD** reference human-readable
documentation for the error being presented.
- ``status`` is a JSON number containing the HTTP status code for the response.
If present, the value of ``status`` is purely advisory.
- ``title`` is a JSON string containing a short, human-readable summary of the problem *type*.
In other words, the ``title`` is covariant with ``type``, and should not vary based on
the individual details of a specific occurrence.
- ``detail`` is a JSON string containing a human-readable explanation of the problem
specific to this occurrence.
- ``instance`` is a JSON string containing a URI reference. Like ``type``, it **MAY**
be a "locator," in which case it **SHOULD** reference human-readable information
about the problem specific to this occurrence.

- Additionally, each Problem Details object **MAY** have additional members, deemed
"extensions." All extensions are optional.

When formatting a response as a Problem Details object, the package index **MUST**
additionally send the ``Content-Type: application/problem+json`` response header.

The following is an example of a Problem Details response:

.. code-block:: json

{
"type": "https://py.example.com/docs/auth-issues",
"status": 403,
"title": "The server is currently haunted.",
"detail": "Consider hiring a priest",
"instance": "https://py.example.com/ORGNAME/..."
}


Clients
~~~~~~~

Upon receipt of an error response from an origin, the client **SHOULD**:

- Confirm that the ``Content-Type`` is ``application/problem+json``. If the ``Content-Type``
is not ``application/problem+json``, the client **MUST NOT** process the response
as if it contains a Problem Details object.
- Deserialize the response body as JSON, and validate it as a Problem Details object.
- Use the contents of the Problem Details object to present a contextually
appropriate error message to the user.

If the process above fails at any step, the client **MAY** handle the original HTTP
error response as it sees fit. This can include handling the error using any pre-existing,
generic HTTP error handling logic.

.. _simple-repository-api-versioning:

Versioning PyPI's Simple API
Expand Down Expand Up @@ -999,3 +1067,4 @@ History
* July 2025: project status markers in the HTML and JSON formats, in :pep:`792`
* July 2025: layout changes (dedicated page for file yanking, introduce concepts before API details)
* June 2026: :pep:`833` formally "freezes" the HTML representation of the simple API
* November 2026: :pep:`847` standardizes error responses for the simple API