Idempotency

Safely retry commands

Commands marked idempotent require Idempotency-Key. Generate a cryptographically random UUID for one logical operation. The server binds it to the principal, method, route template, normalized request hash, and retention window.

curl --request POST 'https://agentranking.io/api/v1/example-command' \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{"example":"value"}'

The same key and same normalized request returns the original result, including an accepted asynchronous operation. The same key with different content returns CONFLICT. Reusing a key after its documented retention window is not safe.

const key = crypto.randomUUID();
async function submit() {
  return fetch("/api/v1/example-command", {
    method: "POST",
    credentials: "same-origin",
    headers: { "content-type": "application/json", "idempotency-key": key },
    body: JSON.stringify({ example: "value" }),
  });
}

Transport timeout does not imply failure. Retry with the same key/body, then reconcile through the returned public operation or resource. Never substitute a queue ID or provider reference for the public operation identifier.