Idempotency (APIs)

An operation is idempotent when performing it several times has the same intended effect on the server as performing it once.

In HTTP. RFC 9110 defines PUT, DELETE and the safe methods, such as GET, as idempotent. Idempotency is what lets a client repeat a request automatically when a connection fails before the response arrives: repeating it cannot do the work twice. The RFC says clients should not automatically retry a non-idempotent request, such as a POST, unless they know it is safe to repeat or can tell it was never applied.

Idempotency keys. Payments and other non-idempotent operations often use a key the client generates and sends with the request. The server stores the outcome under that key and, if the same key arrives again, returns the stored outcome instead of repeating the work. The IETF HTTPAPI working group drafted a standard Idempotency-Key request header for this. The draft suggests 422 Unprocessable Content when a key is reused with a different payload, and 409 Conflict when a retry arrives while the original request is still being processed. Its latest revision, 07, expired in April 2026 without being published as an RFC.

In A2A. Get Task, List Tasks and Get Extended Agent Card are idempotent by nature, and Cancel Task is idempotent: repeated cancellations have the same effect, though a later one may return a task-not-found error once the task has been purged. Send Message may be idempotent, and the specification says agents may use the messageId to detect duplicate messages. A client that retries with the same messageId gives the server that chance. Illustrative A2A v1.0 request, resent unchanged on retry:

{
  "jsonrpc": "2.0",
  "id": "req-18",
  "method": "SendMessage",
  "params": {
    "message": {
      "role": "ROLE_USER",
      "messageId": "3f6c1d2e-8a4b-4c2d-9e1f-5b7a9c0d1e2f",
      "parts": [{"text": "Refund order 1042 to the original card."}]
    }
  }
}

Because duplicate detection is optional, a client cannot assume it. The specification also tells clients that receive push notifications to process them idempotently, since the same update may be delivered more than once.

Neighbouring terms. Rate limiting is a common reason clients retry. A message’s messageId is A2A’s closest equivalent to an idempotency key.