RFC 8516

"Too Many Requests" Response Code for the Constrained Application Protocol

📅 published January 2019, from ietf

RFC 8516: "Too Many Requests" Response Code for the Constrained Application Protocol 🎀

okay bestie, this one is a Standards Track doc from January 2019 (ISSN 2070-1721) 💅 It was written by A. Keranen (Ari Keranen, from Ericsson) and published by the IETF. It doesn't obsolete or update any other RFCs, so it's a clean new addition 🌸

Abstract ✨

okay so a CoAP server can get temporarily overloaded when one or more clients send requests faster than it can handle or is willing to handle 😭 this doc adds a brand new CoAP response code so the server can tell a client to chill out on the request rate 🫶

Status of This Memo 📜

this is an Internet Standards Track document 💜

it's a product of the Internet Engineering Task Force (IETF) and it represents the consensus of the IETF community. it got public review and was approved for publication by the Internet Engineering Steering Group (IESG). if you want more info on Internet Standards, check Section 2 of RFC 7841 🧚

info about the current status of this doc, any errata, and how to give feedback is at https://www.rfc-editor.org/info/rfc8516

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

this doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as in effect on the date of publication. please read these carefully, bestie, because they explain your rights and restrictions for this doc 🙈 code components pulled out of this doc must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in the Simplified BSD License 🌈

Table of Contents 🗺️

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
3.  CoAP Server Behavior  . . . . . . . . . . . . . . . . . . . .   3
4.  CoAP Client Behavior  . . . . . . . . . . . . . . . . . . . .   3
5.  Security Considerations . . . . . . . . . . . . . . . . . . .   4
6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   4
7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   5
  7.1.  Normative References  . . . . . . . . . . . . . . . . . .   5
  7.2.  Informative References  . . . . . . . . . . . . . . . . .   5
Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .   6
Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   6

1. Introduction 💖

okay so CoAP response codes are how a CoAP server says what happened when it tried to understand and satisfy a request from a client 🦋 they're kind of like HTTP status codes, and tons of them have the same meaning in both CoAP and HTTP ✨ HTTP already has 429 registered for "Too Many Requests" [RFC6585]. this doc registers a CoAP response code "4.29" for the same kind of thing, and it uses the Max-Age option (see Section 5.10.5 of [RFC7252]) to say how long of a back-off period a client has before it can try again 🌸

here's the tea: a server might not be able to answer one kind of request, but it could totally answer a different kind of request, even from the same client 👑 so the back-off period only applies to similar requests. for this response code, a request is similar if it has the same method and Request-URI. BUT if a client is sending a series of requests that belong together (like a bunch of measurements the server needs to process), they can count as similar even when the request URIs are different 🧚 because similarity depends on context, it's up to the application logic to decide how to evaluate it ✨

the 4.29 code is kinda like the 5.03 "Service Unavailable" [RFC7252] code, since 5.03 can also be used by a server to signal overload 💅 5.03 also uses the Max-Age option to show when a client can retry. the difference is that 4.29 tells the client that its own too-frequent requests are what caused the overload 🙈

2. Terminology 📚

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 🫶

you should also be familiar with the terms and concepts discussed in [RFC7252] 🌈

3. CoAP Server Behavior 🧚

so if a CoAP server can't serve a client sending CoAP request messages more often than the server can handle or is willing to handle, the server SHOULD respond to those requests with the response code 4.29, "Too Many Requests" 💜 the Max-Age option tells the number of seconds after which the server assumes it's OK for the client to retry 🎀

the server can also send an action result payload (see Section 5.5.1 of [RFC7252]) to give the client more guidance, like details about the overload situation ✨

the 4.29 response code is only sent back to the clients that are sending requests too often. if other clients are sending requests that can't be served because the server is overloaded, the 5.03 response code is the better fit 👑

if a client repeats a request that got a 4.29 before the Max-Age time has passed, it could be because the client sent multiple requests before it got the first answer, or because the client didn't recognize the response code 😭 to slow down clients that don't recognize 4.29, the server MAY respond with a more generic error code (e.g., 5.03) 💅 the server SHOULD rate-limit 4.29 replies, taking its usual load-shedding policies into account 🌸 BUT any method that adds per-client state to the server may backfire and make the load worse instead of better 🙈

4. CoAP Client Behavior 🦋

if a client gets the 4.29 response code from a CoAP server to a request, it SHOULD NOT send a similar request to that server before the time in the Max-Age option has passed 💖 if the 4.29 response doesn't have a Max-Age option, the default value (60 seconds, as defined in Section 5.10.5 of [RFC7252]) is assumed ⭐

heads up: a client can get a 4.29 on its very first request to a server 👀 that can happen if there's a proxy on the path and the server replies based on the load from multiple clients the proxy has combined, or if a client restarted recently and doesn't remember its recent requests 🧚

a client should not rely on a server being able to send the 4.29 response code during an overload, because an overloaded server may not be able to reply at all to some requests 💀

5. Security Considerations 🔥

the security considerations of [RFC7252] apply to this response code too 🔐

replying to CoAP requests uses up resources on a server 😭 for a server under attack, it may be better to just drop requests without responding at all 🙈 BUT dropping requests is also likely to make well-behaving clients simply retry their requests 💀

just like any other CoAP reply, a client should only trust this response code to the extent that it trusts the underlying security mechanisms (e.g., DTLS [RFC6347]) for authentication and freshness 🛡️ if a CoAP reply with the "Too Many Requests" response code isn't authenticated and integrity protected, an attacker can spoof a reply and make the client wait for a long time before trying again 🚨

if the response code is sent without encryption, it may leak information about the server overload situation and the client's traffic patterns. that's a whole privacy leak, bestie 😱

6. IANA Considerations 📋

IANA has registered the following response code in the "CoAP Response Codes" subregistry within the "Constrained RESTful Environments (CoRE) Parameters" registry 🎀

  • Response Code: 4.29
  • Description: Too Many Requests
  • Reference: RFC 8516

IANA has also added this document as an additional reference for the Max-Age option in the "CoAP Option Numbers" subregistry 💖

7. References 📚

7.1. Normative References 💜

[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/info/rfc2119>.

[RFC7252]  Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
           Application Protocol (CoAP)", RFC 7252,
           DOI 10.17487/RFC7252, June 2014,
           <https://www.rfc-editor.org/info/rfc7252>.

[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/info/rfc8174>.

7.2. Informative References 🌸

[CoAP-BROKER]
           Koster, M., Keranen, A., and J. Jimenez, "Publish-
           Subscribe Broker for the Constrained Application Protocol
           (CoAP)", Work in Progress, draft-ietf-core-coap-pubsub-06,
           January 2019.

[RFC6347]  Rescorla, E. and N. Modadugu, "Datagram Transport Layer
           Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347,
           January 2012, <https://www.rfc-editor.org/info/rfc6347>.

[RFC6585]  Nottingham, M. and R. Fielding, "Additional HTTP Status
           Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012,
           <https://www.rfc-editor.org/info/rfc6585>.

[RFC7230]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
           Protocol (HTTP/1.1): Message Syntax and Routing",
           RFC 7230, DOI 10.17487/RFC7230, June 2014,
           <https://www.rfc-editor.org/info/rfc7230>.

Acknowledgements 🫶

this response code definition was originally part of the "Publish-Subscribe Broker for CoAP" doc [CoAP-BROKER] 💖 the author would like to thank Abhijan Bhattacharyya, Carsten Bormann, Daniel Migault, Gyorgy Rethy, Jana Iyengar, Jim Schaad, Klaus Hartke, Mohit Sethi, and Sandor Katona for their contributions and reviews 🌈

Author's Address 💌

Ari Keranen
Ericsson
Hirsalantie 11
02420 Jorvas
Finland

Email: ari.keranen@ericsson.com
📦 where this page comes from