When to use HTTP status code 425 "Too Early"

Question

The 425 "Too Early" status code's description:

Indicates that the server is unwilling to risk processing a request that might be replayed

How is it used in a real world scenario? Examples would be appreciated.

Gavingavini

You've linked to the Using Early Data in HTTP spec, which explains exactly the purpose of the code. Do you have a more specific question? – Cemetery

Yes I read it. What does "User agents that send a request in early data are expected to retry the request when receiving a 425 (Too Early) response status code". If the spec were sufficient there would be no need for SO. That explanation is dry and inaccessible. Hence I'm looking for "real world scenarios" or examples. Do you understand the spec? If so I'd appreciate an explanation. For example what is early data, in the real world. I've never heard of such a thing. – Gavingavini

The introduction explains Early Data: "TLS 1.3 introduces the concept of early data (also known as zero round-trip time (0-RTT) data). If the client has spoken to the same server recently, early data allows a client to send data to a server in the first round trip of a connection, without waiting for the TLS handshake to complete." The spec explains some consequences for HTTP, along with risk mitigations. It is dry, but I can't imagine a better answer than a (simplified rewrite of?) that introduction. – Cemetery

Answer 1

You can use a 425 as an error code to handle idempotent requests.

Real world example: I want a request to my API to send money to someone through some crusty unreliable old banks api. Like 60% of the time the underlying api is fast enough, but 40% of the time clients will time out while waiting. If they retry after a timeout the request could potentially double bill them.

So in my API, I ask the sender to send a transactionId, then when they retry the request, they would resend the same transactionId. On my apis side I'm going to store that transactionId and then start the (potentially long running) money transfer. When the transfer finishes you save the result to the transactionId and then return 200(transferResult) to the sender.

If the client gets impatient and retries then the next web request will see that that transactionId is still in flight and return a 425 Too Early. They can then wait a few seconds and try again getting more 425 Too Early responses until the transfer finishes and you return the 200(transferResult) to the sender.

I know this answer is 6 months late, but maybe that helps understand what a 425 can be used for.

Audreaaudres

Very interesting use case! It's like telling the client "I'm still working on it... relax". It's similar to throttling except for a very narrow scenario. – Gavingavini

I assume there are other use cases too, but yours is the only answer, so I'm accepting. Thanks! – Gavingavini

Answer 2

Use HTTP status codes for their intended use, don't invent your own uses. Both scenarios explained here by other answers would benefit from using more fitting status codes (like 429 which includes a handy header retry-after).

The 425 status code is for a very specific scenario, namely:

• TLS 1.3
• With pre-shared keys
• Having recently had a session
• The client having sent an Early-Data: 1 header
• The TLS layer understanding and accepting the early data, but
• The HTTP server layer not accepting the early request

That's it. That's what it's for. Don't use it for anything else.

https://www.rfc-editor.org/rfc/rfc8446#section-4.2.10, https://datatracker.ietf.org/doc/html/rfc8470#section-1

Aorta

Could you explain where in rfc is written that nobody is allowed to use codes like 425 outside of TLS early data context? The thing is that the common codes are not enough in some cases. Like in TLS it wasn't enough, so they did bring new code. But my brief review haven't found any mention that nobody can reuse that code in different contexts. Inventing custom codes is even worse and using replies like 200 may be misleading in some cases. – Ferrari

It's in the HTTP RFCs. You go find a code and use it if its definition applies; there always is one that fits best. Indeed you don't go invent your own; there's a process for that. Each code has a very specific or more general meaning, and 425 is pretty damn specific. – Aorta

See for example mnot.net/blog/2017/05/11/status_codes - that what is specified in st status code definition, is when it applies. It doesn't apply to all other scenarios. – Aorta

Should I repeat the question in other words or your reply just means that no rfc forbids using exotic codes in own context? – Ferrari

If a recipe says "add sugar", does that explicitly forbid you to add salt? – Aorta

But see for example "When it is necessary to express semantics for a response that are not defined by current status codes, a new status code can be registered." in rfc-editor.org/rfc/rfc9110.html#section-16.2.2. In your answer, you are making up new semantics that, according to the specs, do not apply to the status code as defined. For your answer's scenario, a 201 or 202 would be way more applicable. Definitely not a 4xx which indicates a client error. – Aorta

Kind of agree about 2xx, but I extend existing protocol, so returning 2xx isn't acceptable, because old clients will be confused with absence of data in reply. What I read about new status codes is "it is preferred that new status codes be registered in a document that isn't specific to a single application", which may mean that some codes may be application-specific? Aren't you surprised that no rtc has better explicit message about using specific codes in different contexts? – Ferrari

And yes if receipt says "add sugar", it doesn't forbid adding saccharine in some cases. – Ferrari

Clients not understanding a 201 Created (with a Location header) or 202 Accepted (with a body explaining the client what to do) as the HTTP specs describe, is not a reason to go abuse other status codes so that new clients (and spec-following developers) will have to bend over backwards to talk to your systems. I am not surprised; the HTTP specs describe what you should (or must) do, less so what you shouldn't do. The recipe they give you is "status code X applies to scenario Y". That implicitly excludes all scenarios that aren't Y. There are enough systems out there abusing status codes. – Aorta

Yes the problem is that clients understand 201 and 202, but treat them completely wrong. You see the other answer also describes a situation very similar to mine, where other codes are not suitable. Handling 4** is much more suitable than handling 2** for both cases. I don't have resources to go for official submission of extending 425, but it is certainly possible that it will happen and then most of what you wrote here will be obsolete. While I agree with your message, I disagree with its categoricity. It should be "Try to not use then for anything else". – Ferrari

Answer 3

I use 425 when response is calculated on demand (i.e. the first request), but it may take potentially long to calculate it.

E.g. some reports or metadata can be handled like this.

So after a request to particular resource comes for first time - it gets 425 and a special job is queued for background workers to proceed. Once calculation is finished - further requests to the same resource return 200.

Ferrari