"Too Many Requests" Response Code for the Constrained Application Protocol
Extracted elements (14)
Request similarity for back-off purposes is defined as same method and Request-URI, but application logic may treat a sequence of requests with different URIs as similar if they form a series. Similarity is intentionally context-dependent and left to application logic.
The 4.29 code is distinct from 5.03 'Service Unavailable': 5.03 indicates general server overload (used for clients not causing the overload), while 4.29 specifically signals that the requesting client's high request rate is the cause of the problem.
A client may receive a 4.29 response on a first request if a proxy on the path aggregates load from multiple clients and the server responds based on aggregate load, or if the client restarted and does not remember recent requests.
Clients should not rely on a server being able to send the 4.29 response code in an overload situation, because an overloaded server may not be able to reply to any requests at all.
The 4.29 response code is modeled after HTTP 429 'Too Many Requests' (RFC 6585) and reuses CoAP's existing Max-Age option (RFC 7252 Section 5.10.5) for the retry back-off interval.
If a client receives a 4.29 response, it SHOULD NOT send a similar request to the server before the time indicated in the Max-Age option has passed. If no Max-Age option is present, the default value of 60 seconds applies.
If a client repeats a request answered with 4.29 before Max-Age time has elapsed, the server MAY respond with a more generic error code (e.g., 5.03) to slow down clients that do not recognize the 4.29 code.
If a CoAP server is unable to serve a client sending requests more often than it can handle, the server SHOULD respond with response code 4.29 'Too Many Requests'. The Max-Age option indicates the number of seconds after which the server assumes the client may retry.
The server SHOULD rate-limit 4.29 replies taking into account its usual load-shedding policies, though any method that adds per-client state to the server may be counterproductive.
CoAP response code 4.29 'Too Many Requests' is defined for a server to signal that a client is sending requests more frequently than the server is capable or willing to handle. It uses the Max-Age option to indicate the back-off period after which the client may retry.
IANA registered response code 4.29 'Too Many Requests' in the 'CoAP Response Codes' subregistry within the 'Constrained RESTful Environments (CoRE) Parameters' registry. RFC 8516 was also added as an additional reference for the Max-Age option in the 'CoAP Option Numbers' subregistry.
A client should trust the 4.29 response code only to the extent that it trusts the underlying security mechanisms (e.g., DTLS) for authentication and freshness. An unauthenticated 4.29 response can be spoofed by an attacker to force the client to wait an extended period before retrying.
For a server under attack, it may be more appropriate to drop requests without responding rather than sending 4.29, since replying consumes server resources; however, dropping requests may cause well-behaving clients to simply retry.
If the 4.29 response code is sent without encryption, it may leak information about the server's overload situation and client traffic patterns.