When designing REST endpoints idempotency is a crucial tool. Say we have a HTTP endpoint accepting PUT which we would like to be idempotent.

In case a client makes the same request multiple times, should the server always return the same, or is it acceptable to return an error the second time?

If the answer is yes is restapitutorial.com wrong in writing the following?

"From a RESTful service standpoint, for an operation (or service call) to be idempotent, clients can make that same call repeatedly while producing the same result. In other words, making multiple identical requests has the same effect as making a single request. Note that while idempotent operations produce the same result on the server (no side effects), the response itself may not be the same (e.g. a resource's state may change between requests"

If the answer is yes is a document database implementing optimistic concurrency using get+put not idempotent since the second call would result in an conflict?

If the answer is yes is there a term for services providing the lesser form of guarantee that making the same request more than once has the same effect on the server state as making it exactly once?

  • 4
    It's not an error. If the PUT is idempotent, it should accept the request and produce the same result. Commented Jun 2, 2016 at 21:10
  • 1
    @RobertHarvey HTTP defines "idempotent" only in terms of side-effects, not returned results. See my answer below.
    – Jules
    Commented Jun 3, 2016 at 7:27
  • @robertharvey could you back that up with a reference? Commented Jun 3, 2016 at 9:19

4 Answers 4


According to the HTTP 1.1 specification, idempotence is defined as: "(aside from error or expiration issues) the side-effects of N > 0 identical requests is the same as for a single request". As this definition only discusses the side-effects of the request, and not the content returned, it is acceptable to return different content.


You can return an error on the second put and still be idempotent in the meaning of the term when applied to the http operation PUT.

In this case the idempotency refers to the end result on the server of your operation. Ie if you send two identical PUT requests only one should be actioned.

The clients action on the returned result is not part of idempotent operation.

Obviously, techincaly it is not idempotent. You will have written some logs, maybey returned timestamps in the headers etc etc. But the meaning of the term is you only action one PUT where you would action two POSTs

  • 1
    The HTTP spec clarifies the issue with things like logs as side effects in the section on safe methods by saying "Naturally, it is not possible to ensure that the server does not generate side-effects as a result of performing a GET request; in fact, some dynamic resources consider that a feature. The important distinction here is that the user did not request the side-effects, so therefore cannot be held accountable for them." Probably this should have been written to apply to non-identical side effects of the PUT and DELETE methods.
    – bdsl
    Commented Aug 19, 2018 at 10:52

Returning the same response will allow you to simplify the client implementation as it would need to set the request as sent in its database in both in the case the response was received correctly the first try and in the case the first response was lost and in the next retry the response was correctly got.


"Idempotent" means that making the call has no side effects.

If the call can return an error, then it can return an error on the first request, the second request, both, or none. You might have an access token that is valid for 24 hours; a request one millisecond before the token runs out succeeds, a second request one millisecond later will fail.

However, "Idempotent" does mean that the fact that you made one request mustn't make the second request fail. And the fact that you made one request mustn't make the second request return a different result.

And obviously a resource may be modified from multiple sites, it is absolutely fine if one request returns the current state, and the next request returns the different state of some later time.

  • 1
    Idempotent doesn't mean that. The PUT and DELETE methods are defined specifically to have side effects, and are also supposed to be idempotent.
    – bdsl
    Commented Aug 19, 2018 at 10:53

Not the answer you're looking for? Browse other questions tagged or ask your own question.