title: The 402 (Payment Required) HTTP Status Code abbrev: 402 (Payment Required) docname: draft-nottingham-httpbis-402-latest date: draft-nottingham-httpbis-402-date category: std
ipr: trust200902 keyword: Internet-Draft
stand_alone: yes smart_quotes: no pi: [toc, tocindent, sortrefs, symrefs, strict, compact, comments, inline]
venue: home: "https://projects.mnot.net/I-D/" repo: "https://github.com/mnot/I-D/labels/402"
github-issue-label: 402
ins: M. Nottingham
name: Mark Nottingham
organization: Cloudflare
postal:
- Melbourne
country: Australia
email: mnot@mnot.net
uri: https://mnot.net/
normative: HTTP: RFC9110
--- abstract
This specification defines semantics for the 402 (Payment Required) HTTP status code.
--- middle
{{Section 15.5.3 of HTTP}} says that "The 402 (Payment Required) status code is reserved for future use." To accommodate emerging experimental uses of this status code, {{payment}} defines the status code and establishes guidelines for its use.
{::boilerplate bcp14-tagged}
The 402 (Payment Required) status code indicates that the resource requires payment before it will satisfy the request, and that no acceptable payment has been made.
This status code does not indicate the form of the payment, what it covers (e.g., one request, a period of access, or a set of resources), or whether an earlier payment was attempted and found unacceptable.
Therefore, a server generating a 402 response SHOULD indicate how a payment can be made, so that clients can make a payment and retry the request. This might be done using header fields ({{Section 6.3 of HTTP}}) and/or the response content ({{Section 6.4 of HTTP}}).
Any server can generate this status code, including an intermediary ({{Section 3.7 of HTTP}}) that requires payment for forwarding the request.
A 402 (Payment Required) response is not heuristically cacheable ({{Section 15.1 of HTTP}}).
IANA should update the Hypertext Transfer Protocol (HTTP) Status Code Registry to refer the entry for the 402 status code to this document upon publication.
HTTP does not authenticate the sender of a response beyond what the underlying connection provides, and a 402 (Payment Required) response can be generated by an intermediary ({{Section 3.7 of HTTP}}) as readily as by the origin server. An attacker who can insert or modify responses can therefore substitute their own payment information and have the payment directed to them, or can demand payment where none was required. Clients SHOULD NOT act upon payment information in a response that was not received over an authenticated connection (see {{Section 4.3.4 of HTTP}}).
More generally, a resource can demand an arbitrary amount for any request, and can demand payment again after one has been made; clients that pay without direct human involvement need constraints on how much, how often, and to whom they will pay.
Payment requirements often depend on who is asking and what they have already paid, so 402 (Payment Required) responses might carry client-specific information -- amounts owed, transaction references, or identifiers for the payer. Servers need to prevent such responses being stored and reused for other clients by a shared cache, either by making them uncacheable or by using Vary ({{Section 12.5.5 of HTTP}}); note that Vary can only be keyed on request header fields, so a requirement that depends on state not carried in the request cannot be expressed that way.
Making a payment can also link a client's requests to a payment instrument, and thereby to a person, so a client that is otherwise unidentified should treat the decision to pay as one that discloses identity.
--- back