The 402 (Payment Required) HTTP Status Code
draft-nottingham-httpbis-402-00

Network Working Group                                      M. Nottingham
Internet-Draft                                                Cloudflare
Intended status: Standards Track                          30 August 2026
Expires: 3 March 2027

              The 402 (Payment Required) HTTP Status Code
                    draft-nottingham-httpbis-402-00

Abstract

   This specification defines semantics for the 402 (Payment Required)
   HTTP status code.

About This Document

   This note is to be removed before publishing as an RFC.

   Status information for this document may be found at
   https://datatracker.ietf.org/doc/draft-nottingham-httpbis-402/.

   information can be found at https://projects.mnot.net/I-D/.

   Source for this draft and an issue tracker can be found at
   https://github.com/mnot/I-D/labels/402.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 3 March 2027.

Copyright Notice

   Copyright (c) 2026 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

Nottingham                Expires 3 March 2027                  [Page 1]
Internet-Draft           402 (Payment Required)              August 2026

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Notational Conventions  . . . . . . . . . . . . . . . . .   2
   2.  402 Payment Required  . . . . . . . . . . . . . . . . . . . .   2
   3.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   3
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .   3
   5.  Normative References  . . . . . . . . . . . . . . . . . . . .   4
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   4

1.  Introduction

   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, Section 2 defines the status
   code and establishes guidelines for its use.

1.1.  Notational Conventions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

2.  402 Payment Required

   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.

Nottingham                Expires 3 March 2027                  [Page 2]
Internet-Draft           402 (Payment Required)              August 2026

   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]).

3.  IANA Considerations

   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.

4.  Security Considerations

   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.

Nottingham                Expires 3 March 2027                  [Page 3]
Internet-Draft           402 (Payment Required)              August 2026

   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.

5.  Normative References

   [HTTP]     Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
              Ed., "HTTP Semantics", STD 97, RFC 9110,
              DOI 10.17487/RFC9110, June 2022,
              <https://www.rfc-editor.org/rfc/rfc9110>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/rfc/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

Author's Address

   Mark Nottingham
   Cloudflare
   Melbourne
   Australia
   Email: mnot@mnot.net
   URI:   https://mnot.net/

Nottingham                Expires 3 March 2027                  [Page 4]