1:mod:`http` --- HTTP modules
2============================
3
4.. module:: http
5   :synopsis: HTTP status codes and messages
6
7**Source code:** :source:`Lib/http/__init__.py`
8
9.. index::
10   pair: HTTP; protocol
11   single: HTTP; http (standard module)
12
13--------------
14
15:mod:`http` is a package that collects several modules for working with the
16HyperText Transfer Protocol:
17
18* :mod:`http.client` is a low-level HTTP protocol client; for high-level URL
19  opening use :mod:`urllib.request`
20* :mod:`http.server` contains basic HTTP server classes based on :mod:`socketserver`
21* :mod:`http.cookies` has utilities for implementing state management with cookies
22* :mod:`http.cookiejar` provides persistence of cookies
23
24:mod:`http` is also a module that defines a number of HTTP status codes and
25associated messages through the :class:`http.HTTPStatus` enum:
26
27.. class:: HTTPStatus
28
29   .. versionadded:: 3.5
30
31   A subclass of :class:`enum.IntEnum` that defines a set of HTTP status codes,
32   reason phrases and long descriptions written in English.
33
34   Usage::
35
36      >>> from http import HTTPStatus
37      >>> HTTPStatus.OK
38      HTTPStatus.OK
39      >>> HTTPStatus.OK == 200
40      True
41      >>> HTTPStatus.OK.value
42      200
43      >>> HTTPStatus.OK.phrase
44      'OK'
45      >>> HTTPStatus.OK.description
46      'Request fulfilled, document follows'
47      >>> list(HTTPStatus)
48      [HTTPStatus.CONTINUE, HTTPStatus.SWITCHING_PROTOCOLS, ...]
49
50.. _http-status-codes:
51
52HTTP status codes
53-----------------
54
55Supported,
56`IANA-registered <https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml>`_
57status codes available in :class:`http.HTTPStatus` are:
58
59======= =================================== ==================================================================
60Code    Enum Name                           Details
61======= =================================== ==================================================================
62``100`` ``CONTINUE``                        HTTP/1.1 :rfc:`7231`, Section 6.2.1
63``101`` ``SWITCHING_PROTOCOLS``             HTTP/1.1 :rfc:`7231`, Section 6.2.2
64``102`` ``PROCESSING``                      WebDAV :rfc:`2518`, Section 10.1
65``103`` ``EARLY_HINTS``                     An HTTP Status Code for Indicating Hints :rfc:`8297`
66``200`` ``OK``                              HTTP/1.1 :rfc:`7231`, Section 6.3.1
67``201`` ``CREATED``                         HTTP/1.1 :rfc:`7231`, Section 6.3.2
68``202`` ``ACCEPTED``                        HTTP/1.1 :rfc:`7231`, Section 6.3.3
69``203`` ``NON_AUTHORITATIVE_INFORMATION``   HTTP/1.1 :rfc:`7231`, Section 6.3.4
70``204`` ``NO_CONTENT``                      HTTP/1.1 :rfc:`7231`, Section 6.3.5
71``205`` ``RESET_CONTENT``                   HTTP/1.1 :rfc:`7231`, Section 6.3.6
72``206`` ``PARTIAL_CONTENT``                 HTTP/1.1 :rfc:`7233`, Section 4.1
73``207`` ``MULTI_STATUS``                    WebDAV :rfc:`4918`, Section 11.1
74``208`` ``ALREADY_REPORTED``                WebDAV Binding Extensions :rfc:`5842`, Section 7.1 (Experimental)
75``226`` ``IM_USED``                         Delta Encoding in HTTP :rfc:`3229`, Section 10.4.1
76``300`` ``MULTIPLE_CHOICES``                HTTP/1.1 :rfc:`7231`, Section 6.4.1
77``301`` ``MOVED_PERMANENTLY``               HTTP/1.1 :rfc:`7231`, Section 6.4.2
78``302`` ``FOUND``                           HTTP/1.1 :rfc:`7231`, Section 6.4.3
79``303`` ``SEE_OTHER``                       HTTP/1.1 :rfc:`7231`, Section 6.4.4
80``304`` ``NOT_MODIFIED``                    HTTP/1.1 :rfc:`7232`, Section 4.1
81``305`` ``USE_PROXY``                       HTTP/1.1 :rfc:`7231`, Section 6.4.5
82``307`` ``TEMPORARY_REDIRECT``              HTTP/1.1 :rfc:`7231`, Section 6.4.7
83``308`` ``PERMANENT_REDIRECT``              Permanent Redirect :rfc:`7238`, Section 3 (Experimental)
84``400`` ``BAD_REQUEST``                     HTTP/1.1 :rfc:`7231`, Section 6.5.1
85``401`` ``UNAUTHORIZED``                    HTTP/1.1 Authentication :rfc:`7235`, Section 3.1
86``402`` ``PAYMENT_REQUIRED``                HTTP/1.1 :rfc:`7231`, Section 6.5.2
87``403`` ``FORBIDDEN``                       HTTP/1.1 :rfc:`7231`, Section 6.5.3
88``404`` ``NOT_FOUND``                       HTTP/1.1 :rfc:`7231`, Section 6.5.4
89``405`` ``METHOD_NOT_ALLOWED``              HTTP/1.1 :rfc:`7231`, Section 6.5.5
90``406`` ``NOT_ACCEPTABLE``                  HTTP/1.1 :rfc:`7231`, Section 6.5.6
91``407`` ``PROXY_AUTHENTICATION_REQUIRED``   HTTP/1.1 Authentication :rfc:`7235`, Section 3.2
92``408`` ``REQUEST_TIMEOUT``                 HTTP/1.1 :rfc:`7231`, Section 6.5.7
93``409`` ``CONFLICT``                        HTTP/1.1 :rfc:`7231`, Section 6.5.8
94``410`` ``GONE``                            HTTP/1.1 :rfc:`7231`, Section 6.5.9
95``411`` ``LENGTH_REQUIRED``                 HTTP/1.1 :rfc:`7231`, Section 6.5.10
96``412`` ``PRECONDITION_FAILED``             HTTP/1.1 :rfc:`7232`, Section 4.2
97``413`` ``REQUEST_ENTITY_TOO_LARGE``        HTTP/1.1 :rfc:`7231`, Section 6.5.11
98``414`` ``REQUEST_URI_TOO_LONG``            HTTP/1.1 :rfc:`7231`, Section 6.5.12
99``415`` ``UNSUPPORTED_MEDIA_TYPE``          HTTP/1.1 :rfc:`7231`, Section 6.5.13
100``416`` ``REQUESTED_RANGE_NOT_SATISFIABLE`` HTTP/1.1 Range Requests :rfc:`7233`, Section 4.4
101``417`` ``EXPECTATION_FAILED``              HTTP/1.1 :rfc:`7231`, Section 6.5.14
102``418`` ``IM_A_TEAPOT``                     HTCPCP/1.0 :rfc:`2324`, Section 2.3.2
103``421`` ``MISDIRECTED_REQUEST``             HTTP/2 :rfc:`7540`, Section 9.1.2
104``422`` ``UNPROCESSABLE_ENTITY``            WebDAV :rfc:`4918`, Section 11.2
105``423`` ``LOCKED``                          WebDAV :rfc:`4918`, Section 11.3
106``424`` ``FAILED_DEPENDENCY``               WebDAV :rfc:`4918`, Section 11.4
107``425`` ``TOO_EARLY``                       Using Early Data in HTTP :rfc:`8470`
108``426`` ``UPGRADE_REQUIRED``                HTTP/1.1 :rfc:`7231`, Section 6.5.15
109``428`` ``PRECONDITION_REQUIRED``           Additional HTTP Status Codes :rfc:`6585`
110``429`` ``TOO_MANY_REQUESTS``               Additional HTTP Status Codes :rfc:`6585`
111``431`` ``REQUEST_HEADER_FIELDS_TOO_LARGE`` Additional HTTP Status Codes :rfc:`6585`
112``451`` ``UNAVAILABLE_FOR_LEGAL_REASONS``   An HTTP Status Code to Report Legal Obstacles :rfc:`7725`
113``500`` ``INTERNAL_SERVER_ERROR``           HTTP/1.1 :rfc:`7231`, Section 6.6.1
114``501`` ``NOT_IMPLEMENTED``                 HTTP/1.1 :rfc:`7231`, Section 6.6.2
115``502`` ``BAD_GATEWAY``                     HTTP/1.1 :rfc:`7231`, Section 6.6.3
116``503`` ``SERVICE_UNAVAILABLE``             HTTP/1.1 :rfc:`7231`, Section 6.6.4
117``504`` ``GATEWAY_TIMEOUT``                 HTTP/1.1 :rfc:`7231`, Section 6.6.5
118``505`` ``HTTP_VERSION_NOT_SUPPORTED``      HTTP/1.1 :rfc:`7231`, Section 6.6.6
119``506`` ``VARIANT_ALSO_NEGOTIATES``         Transparent Content Negotiation in HTTP :rfc:`2295`, Section 8.1 (Experimental)
120``507`` ``INSUFFICIENT_STORAGE``            WebDAV :rfc:`4918`, Section 11.5
121``508`` ``LOOP_DETECTED``                   WebDAV Binding Extensions :rfc:`5842`, Section 7.2 (Experimental)
122``510`` ``NOT_EXTENDED``                    An HTTP Extension Framework :rfc:`2774`, Section 7 (Experimental)
123``511`` ``NETWORK_AUTHENTICATION_REQUIRED`` Additional HTTP Status Codes :rfc:`6585`, Section 6
124======= =================================== ==================================================================
125
126In order to preserve backwards compatibility, enum values are also present
127in the :mod:`http.client` module in the form of constants. The enum name is
128equal to the constant name (i.e. ``http.HTTPStatus.OK`` is also available as
129``http.client.OK``).
130
131.. versionchanged:: 3.7
132   Added ``421 MISDIRECTED_REQUEST`` status code.
133
134.. versionadded:: 3.8
135   Added ``451 UNAVAILABLE_FOR_LEGAL_REASONS`` status code.
136
137.. versionadded:: 3.9
138   Added ``103 EARLY_HINTS``, ``418 IM_A_TEAPOT`` and ``425 TOO_EARLY`` status codes.
139