resthttp-status-codes

When to use HTTP status code 425 "Too Early"


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.


Solution

  • 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.