Skip to content

Commit 0baf0f5

Browse files
committed
simple-api: add PEP 847
Signed-off-by: William Woodruff <william@yossarian.net>
1 parent 5ecbc0d commit 0baf0f5

1 file changed

Lines changed: 52 additions & 0 deletions

File tree

‎source/specifications/simple-repository-api.rst‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,57 @@ can be implemented in Python with the ``re`` module::
4444
def normalize(name):
4545
return re.sub(r"[-_.]+", "-", name).lower()
4646

47+
48+
.. _simple-repository-api-error-responses:
49+
50+
Error Responses
51+
---------------
52+
53+
If a response to the simple API cannot be honored, the simple API **MUST** respond
54+
with an appropriate HTTP error code (in the range 400-499 or 500-599).
55+
56+
When preparing to send an error response to a requester (e.g., an installer client),
57+
the package index **SHOULD** format its response as an
58+
:rfc:`RFC 9457 Problem Details object <9457#section-3>`.
59+
60+
Implementers should consult :rfc:`9457` for a fully detailed description of the
61+
Problem Details object format. The following is an abbreviated description:
62+
63+
- Each Problem Details object is a JSON (:rfc:`8259`) object.
64+
- Each Problem Details object **MAY** have the following members. All members are optional.
65+
66+
- ``type`` is a JSON string containing a URI reference. It **MAY** be a "locator,"
67+
i.e. an HTTP or HTTPS URI, in which case it **SHOULD** reference human-readable
68+
documentation for the error being presented.
69+
- ``status`` is a JSON number containing the HTTP status code for the response.
70+
If present, the value of ``status`` is purely advisory.
71+
- ``title`` is a JSON string containing a short, human-readable summary of the problem *type*.
72+
In other words, the ``title`` is covariant with ``type``, and should not vary based on
73+
the individual details of a specific occurrence.
74+
- ``detail`` is a JSON string containing a human-readable explanation of the problem
75+
specific to this occurrence.
76+
- ``instance`` is a JSON string containing a URI reference. Like ``type``, it **MAY**
77+
be a "locator," in which case it **SHOULD** reference human-readable information
78+
about the problem specific to this occurrence.
79+
80+
- Additionally, each Problem Details object **MAY** have additional members, deemed
81+
"extensions." All extensions are optional.
82+
83+
When formatting a response as a Problem Details object, the package index **MUST**
84+
additionally send the ``Content-Type: application/problem+json`` response header.
85+
86+
The following is an example of a Problem Details response:
87+
88+
.. code-block:: json
89+
90+
{
91+
"type": "https://py.example.com/docs/auth-issues",
92+
"status": 403,
93+
"title": "The server is currently haunted.",
94+
"detail": "Consider hiring a priest",
95+
"instance": "https://py.example.com/ORGNAME/..."
96+
}
97+
4798
.. _simple-repository-api-versioning:
4899

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

0 commit comments

Comments
 (0)