@@ -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
49100Versioning 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