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: 200>
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: 100>, <HTTPStatus.SWITCHING_PROTOCOLS: 101>, ...]
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``200`` ``OK``                              HTTP/1.1 :rfc:`7231`, Section 6.3.1
66``201`` ``CREATED``                         HTTP/1.1 :rfc:`7231`, Section 6.3.2
67``202`` ``ACCEPTED``                        HTTP/1.1 :rfc:`7231`, Section 6.3.3
68``203`` ``NON_AUTHORITATIVE_INFORMATION``   HTTP/1.1 :rfc:`7231`, Section 6.3.4
69``204`` ``NO_CONTENT``                      HTTP/1.1 :rfc:`7231`, Section 6.3.5
70``205`` ``RESET_CONTENT``                   HTTP/1.1 :rfc:`7231`, Section 6.3.6
71``206`` ``PARTIAL_CONTENT``                 HTTP/1.1 :rfc:`7233`, Section 4.1
72``207`` ``MULTI_STATUS``                    WebDAV :rfc:`4918`, Section 11.1
73``208`` ``ALREADY_REPORTED``                WebDAV Binding Extensions :rfc:`5842`, Section 7.1 (Experimental)
74``226`` ``IM_USED``                         Delta Encoding in HTTP :rfc:`3229`, Section 10.4.1
75``300`` ``MULTIPLE_CHOICES``                HTTP/1.1 :rfc:`7231`, Section 6.4.1
76``301`` ``MOVED_PERMANENTLY``               HTTP/1.1 :rfc:`7231`, Section 6.4.2
77``302`` ``FOUND``                           HTTP/1.1 :rfc:`7231`, Section 6.4.3
78``303`` ``SEE_OTHER``                       HTTP/1.1 :rfc:`7231`, Section 6.4.4
79``304`` ``NOT_MODIFIED``                    HTTP/1.1 :rfc:`7232`, Section 4.1
80``305`` ``USE_PROXY``                       HTTP/1.1 :rfc:`7231`, Section 6.4.5
81``307`` ``TEMPORARY_REDIRECT``              HTTP/1.1 :rfc:`7231`, Section 6.4.7
82``308`` ``PERMANENT_REDIRECT``              Permanent Redirect :rfc:`7238`, Section 3 (Experimental)
83``400`` ``BAD_REQUEST``                     HTTP/1.1 :rfc:`7231`, Section 6.5.1
84``401`` ``UNAUTHORIZED``                    HTTP/1.1 Authentication :rfc:`7235`, Section 3.1
85``402`` ``PAYMENT_REQUIRED``                HTTP/1.1 :rfc:`7231`, Section 6.5.2
86``403`` ``FORBIDDEN``                       HTTP/1.1 :rfc:`7231`, Section 6.5.3
87``404`` ``NOT_FOUND``                       HTTP/1.1 :rfc:`7231`, Section 6.5.4
88``405`` ``METHOD_NOT_ALLOWED``              HTTP/1.1 :rfc:`7231`, Section 6.5.5
89``406`` ``NOT_ACCEPTABLE``                  HTTP/1.1 :rfc:`7231`, Section 6.5.6
90``407`` ``PROXY_AUTHENTICATION_REQUIRED``   HTTP/1.1 Authentication :rfc:`7235`, Section 3.2
91``408`` ``REQUEST_TIMEOUT``                 HTTP/1.1 :rfc:`7231`, Section 6.5.7
92``409`` ``CONFLICT``                        HTTP/1.1 :rfc:`7231`, Section 6.5.8
93``410`` ``GONE``                            HTTP/1.1 :rfc:`7231`, Section 6.5.9
94``411`` ``LENGTH_REQUIRED``                 HTTP/1.1 :rfc:`7231`, Section 6.5.10
95``412`` ``PRECONDITION_FAILED``             HTTP/1.1 :rfc:`7232`, Section 4.2
96``413`` ``REQUEST_ENTITY_TOO_LARGE``        HTTP/1.1 :rfc:`7231`, Section 6.5.11
97``414`` ``REQUEST_URI_TOO_LONG``            HTTP/1.1 :rfc:`7231`, Section 6.5.12
98``415`` ``UNSUPPORTED_MEDIA_TYPE``          HTTP/1.1 :rfc:`7231`, Section 6.5.13
99``416`` ``REQUESTED_RANGE_NOT_SATISFIABLE`` HTTP/1.1 Range Requests :rfc:`7233`, Section 4.4
100``417`` ``EXPECTATION_FAILED``              HTTP/1.1 :rfc:`7231`, Section 6.5.14
101``421`` ``MISDIRECTED_REQUEST``             HTTP/2 :rfc:`7540`, Section 9.1.2
102``422`` ``UNPROCESSABLE_ENTITY``            WebDAV :rfc:`4918`, Section 11.2
103``423`` ``LOCKED``                          WebDAV :rfc:`4918`, Section 11.3
104``424`` ``FAILED_DEPENDENCY``               WebDAV :rfc:`4918`, Section 11.4
105``426`` ``UPGRADE_REQUIRED``                HTTP/1.1 :rfc:`7231`, Section 6.5.15
106``428`` ``PRECONDITION_REQUIRED``           Additional HTTP Status Codes :rfc:`6585`
107``429`` ``TOO_MANY_REQUESTS``               Additional HTTP Status Codes :rfc:`6585`
108``431`` ``REQUEST_HEADER_FIELDS_TOO_LARGE`` Additional HTTP Status Codes :rfc:`6585`
109``451`` ``UNAVAILABLE_FOR_LEGAL_REASONS``   An HTTP Status Code to Report Legal Obstacles :rfc:`7725`
110``500`` ``INTERNAL_SERVER_ERROR``           HTTP/1.1 :rfc:`7231`, Section 6.6.1
111``501`` ``NOT_IMPLEMENTED``                 HTTP/1.1 :rfc:`7231`, Section 6.6.2
112``502`` ``BAD_GATEWAY``                     HTTP/1.1 :rfc:`7231`, Section 6.6.3
113``503`` ``SERVICE_UNAVAILABLE``             HTTP/1.1 :rfc:`7231`, Section 6.6.4
114``504`` ``GATEWAY_TIMEOUT``                 HTTP/1.1 :rfc:`7231`, Section 6.6.5
115``505`` ``HTTP_VERSION_NOT_SUPPORTED``      HTTP/1.1 :rfc:`7231`, Section 6.6.6
116``506`` ``VARIANT_ALSO_NEGOTIATES``         Transparent Content Negotiation in HTTP :rfc:`2295`, Section 8.1 (Experimental)
117``507`` ``INSUFFICIENT_STORAGE``            WebDAV :rfc:`4918`, Section 11.5
118``508`` ``LOOP_DETECTED``                   WebDAV Binding Extensions :rfc:`5842`, Section 7.2 (Experimental)
119``510`` ``NOT_EXTENDED``                    An HTTP Extension Framework :rfc:`2774`, Section 7 (Experimental)
120``511`` ``NETWORK_AUTHENTICATION_REQUIRED`` Additional HTTP Status Codes :rfc:`6585`, Section 6
121======= =================================== ==================================================================
122
123In order to preserve backwards compatibility, enum values are also present
124in the :mod:`http.client` module in the form of constants. The enum name is
125equal to the constant name (i.e. ``http.HTTPStatus.OK`` is also available as
126``http.client.OK``).
127
128.. versionchanged:: 3.7
129   Added ``421 MISDIRECTED_REQUEST`` status code.
130
131.. versionadded:: 3.8
132   Added ``451 UNAVAILABLE_FOR_LEGAL_REASONS`` status code.
133