Idempotency, concurrency and limits

Networks drop answers, servers restart and agents run in parallel. This chapter is the contract for those moments: how to make a write safe to repeat, what happens when two requests touch one session, which errors to retry and how often, the exact rate limits and timeouts, what is cached, how long a session lives, and how to wait for the buyer's order without wasting your budget. The codes themselves are explained in Errors and messages.

The examples use the shop https://shop.example.com and a platform whose profile is https://platform.example.com/.well-known/ucp.

Idempotency-Key

A write sent twice — because the answer never arrived, or a worker restarted — must not create two carts. The Idempotency-Key header makes that safe: the shop runs the first request, stores its answer, and answers every repeat of the same request with the stored answer.

Which operations

Only the seven writes read the header. Everything else ignores it.

The catalog operations, GET of a cart or a checkout, the business profile and the handoff routes never read it: they change nothing a retry could duplicate.

The key

• Format: 1–255 printable ASCII characters from ! to ~ — no spaces, no letters outside ASCII. Anything else is 400 invalid_request Idempotency-Key is not valid, and nothing runs. Send the header once: a header sent twice arrives joined with ", ", which contains a space.
• One key per logical write. Generate it when you decide to make the write — a version 4 UUID is a good choice — and send the same key, with the same body, on every retry of that write. A different write gets a different key, even when its body happens to be equal.
• Keep it with the pending write. If your worker can restart between attempts, store the key with the operation before the first attempt, so the retry after a restart sends the same key.
• The header is optional. Without it, or with an empty value, the write simply runs. See Without a key.

KEY=$(uuidgen)   # generated once for this write; every retry below reuses it
curl -sS -X POST https://shop.example.com/ucp/v1/carts \
  -H 'UCP-Agent: profile="https://platform.example.com/.well-known/ucp"' \
  -H "Idempotency-Key: $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"line_items":[{"item":{"id":"1e8a6c4f-2b93-4d71-9f05-6a3c8e2b1d47"},"quantity":1}],"context":{"language":"sk"}}'

import { randomUUID } from 'node:crypto';

// Persist { key, body } with the pending write before the first attempt.
const pending = { key: randomUUID(), body: { line_items: [{ item: { id: VARIANT_ID }, quantity: 1 }] } };

import uuid

# Persist key and body with the pending write before the first attempt.
pending = {"key": str(uuid.uuid4()), "body": {"line_items": [{"item": {"id": VARIANT_ID}, "quantity": 1}]}}

Scope and fingerprint

A stored key belongs to one shop, to your exact profile URL — the string in UCP-Agent, compared character by character — and to the key itself. Another platform that happens to send the same key never sees your answer, and the same key on two different shops is two different keys. All domains of one shop share its keys.

The request the key was first used for is remembered as a fingerprint of the operation, the path id exactly as you sent it, and the body. The body is compared as JSON: the order of object keys and the whitespace do not matter; the order of array entries does. The path id is compared as a string, so an upper-case spelling of the same id is a different request.

Keep your profile URL stable: a retry under another profile URL — even one with a different query string — is a first use of the key.

What a repeat gets

A replay is the answer of the first request, not a fresh read: its expires_at, prices and messages are those of that moment. Its JSON object keys can be ordered differently from the first answer (key order carries no meaning), so its ETag can differ too. After a replay, GET the session when you need its current state. Nothing in the answer marks it as a replay.

How long keys are kept

A key is kept for 25 hours from the moment it was claimed. An hourly job deletes the older ones, so a key disappears between 25 and about 26 hours after its claim. After that, the same key is a first use again. Never reuse a key for another write, and do not rely on protection for a retry more than 24 hours after the first attempt.

Without a key

A write without Idempotency-Key runs every time it arrives:

Send a key on every write. It costs nothing, and a retried create is the most common way to lose track of a buyer's session.

Concurrency

One request at a time per session

Every request that may change a session waits for its turn: requests on one cart or checkout run one after the other, in the order they arrive at the API server.

A checkout GET takes a turn too, because a read may store a status that changed (an expired checkout is canceled by the read that finds it).

The operation behind such a 503 never ran, and its Idempotency-Key was released: repeat the same request with the same key after a second. The queue limit applies per API server process; across processes a database lock keeps the one-at-a-time rule.

Send at most one request per session at a time. Parallel writes on one session gain nothing — they run one after the other anyway — and a burst of them can starve the buyer's handoff, which waits for the same turn.

A write that loses a race

Two things change a checkout without taking its turn: the buyer's order on the shop, which completes it, and a new conversion of its cart, which cancels it once it has expired. Every session write is therefore applied only if the session has not changed since the request read it. When a write loses that race:

Sessions have no version number you could send: there is no If-Match, and none is needed — the server does the comparison.

One open checkout per cart

A cart has at most one open checkout. Two conversions of the same cart at the same moment both answer the same checkout: one with 201, the other with 200. To change that checkout, PUT it; converting the cart again changes nothing.

Retries

Use at most 5 attempts per logical call, an exponential backoff of 1, 2, 4, 8 seconds with random jitter and a ceiling of 30 seconds, and the Retry-After value instead of the backoff whenever the answer carries one. Send the same body on every attempt — the same JSON; key order and whitespace may differ, the order of array entries may not — or the key answers 409.

A write whose attempts all ended without a definitive answer — network errors, 502, 504, 409 with Retry-After — may have run, and there is no way to list your sessions and find it. Do not drop it: keep its key and body with the pending write and send the same request again later. While the first attempt still runs, the retry gets 409 with Retry-After: 2; once it has finished, the stored answer; and if it died, the same request takes the key over 120 seconds after its claim and runs the write. If it never reached the API, the retry is the key's first use. A new key instead would make a second session.

import { randomUUID } from 'node:crypto';
import { setTimeout as sleep } from 'node:timers/promises';

const RETRYABLE = new Set([429, 500, 502, 503, 504]);
const backoff = (attempt) => Math.min(30_000, 1000 * 2 ** (attempt - 1)) * (0.5 + Math.random() / 2);

// One logical UCP call. Every retry reuses the same Idempotency-Key and body.
export async function ucpCall(method, url, { profileUrl, body, key, maxAttempts = 5 } = {}) {
  const write = method !== 'GET' && !url.includes('/catalog/');
  key ??= write ? randomUUID() : undefined;
  for (let attempt = 1; ; attempt++) {
    let res;
    try {
      res = await fetch(url, {
        method,
        redirect: 'error', // the API never redirects; http:// is a mistake, not a hop
        headers: {
          'UCP-Agent': `profile="${profileUrl}"`,
          ...(body !== undefined && { 'Content-Type': 'application/json' }),
          ...(key && { 'Idempotency-Key': key }),
        },
        body: body === undefined ? undefined : JSON.stringify(body),
        signal: AbortSignal.timeout(65_000), // the web server gives up after 60 s
      });
    } catch (err) {
      if (attempt >= maxAttempts) throw err; // no answer: the same key makes the retry safe
      await sleep(backoff(attempt));
      continue;
    }
    const stillRunning = res.status === 409 && res.headers.has('retry-after');
    if ((RETRYABLE.has(res.status) || stillRunning) && attempt < maxAttempts) {
      const retryAfter = Number(res.headers.get('retry-after'));
      await sleep(retryAfter > 0 ? retryAfter * 1000 : backoff(attempt));
      continue;
    }
    return res; // final: classify it as in Errors and messages
  }
}

import random, time, uuid
import requests

RETRYABLE = {429, 500, 502, 503, 504}

def backoff(attempt):
    return min(30, 2 ** (attempt - 1)) * random.uniform(0.5, 1.0)

def ucp_call(method, url, profile_url, body=None, key=None, max_attempts=5):
    """One logical UCP call. Every retry reuses the same Idempotency-Key and body."""
    write = method != "GET" and "/catalog/" not in url
    key = key or (str(uuid.uuid4()) if write else None)
    headers = {"UCP-Agent": f'profile="{profile_url}"'}
    if key:
        headers["Idempotency-Key"] = key
    for attempt in range(1, max_attempts + 1):
        try:
            r = requests.request(method, url, json=body, headers=headers,
                                 timeout=65, allow_redirects=False)
        except requests.RequestException:
            if attempt == max_attempts:
                raise  # no answer: the same key makes the retry safe
            time.sleep(backoff(attempt))
            continue
        still_running = r.status_code == 409 and "Retry-After" in r.headers
        if (r.status_code in RETRYABLE or still_running) and attempt < max_attempts:
            retry_after = r.headers.get("Retry-After", "")
            time.sleep(int(retry_after) if retry_after.isdigit() else backoff(attempt))
            continue
        return r  # final: classify it as in Errors and messages

A 429 or a 503 for the shop asks for a minute's wait. A conversational agent should tell the buyer it is waiting, or give up and come back, rather than block silently.

Rate limits

The API

Each operation has its own limit per client IP address, over 60 seconds:

• Each operation counts separately: 600 searches and 600 checkout reads in the same minute are both within the limits.
• Your IP address is the key, not the shop and not your profile: one egress IP shares each operation's budget across every Monokaido shop. The address is the one the web server sees; an X-Forwarded-For you send is not used.
• Each request counts for 60 seconds — in principle. The request that would exceed the limit is refused and starts a 60-second block of that operation for your IP; every request in the block gets 429 rate_limited with Retry-After: 60, and the count starts from zero when the block ends.
• The count does not always fall back. The counts are kept in the API server's memory (a restart clears them). Each request is meant to leave the count 60 seconds after it was made, but the rate limiter the API uses (@nestjs/throttler 6.5) drops those pending decrements — of every client at once — whenever any client's block ends. From then on your count only grows, until it reaches the limit and your own 429 block resets it. Treat each limit as a budget, not as a rate: keep steady traffic at half of it or less, and on a 429 wait the full Retry-After.
• Headers. Every answer that passed the limiter carries X-RateLimit-Limit (the operation's limit), X-RateLimit-Remaining (the limit minus your current count) and X-RateLimit-Reset (seconds left in a 60-second window the limiter keeps per IP and operation; the count is not reset when that window ends, so it does not tell you when the budget comes back). Watch X-RateLimit-Remaining and slow down well before it reaches zero. A 429 carries Retry-After instead.

The handoff limits are counted for the buyer's IP, not yours. Buyers behind one shared address — an office network, say — share those 60 a minute.

The web server

In front of the API, the web server allows 100 requests a second per IP, with a burst of 200, counted over all storefront traffic from that IP: the UCP calls of every shop and the shops' own pages and images. Above it the answer is the web server's own HTML 429, without Retry-After. Back off and retry, starting at one second.

New platform profiles

Fetching a platform profile the shop's server does not know yet is limited: 5 new profile URLs a minute per client (one IPv4 address, or one IPv6 /64) and 60 a minute in all. Over it, the answer is 503 with a Retry-After. A profile the server already knows never counts, so one stable profile URL is never affected.

Planning capacity

Because a count may not fall back (see above), these figures hold only while your traffic stays well under the limit; a pattern that runs at the full limit for long gets 429 blocks.

If one egress IP serves many buyers at once, spread the traffic over several addresses or lengthen the polling interval (see Waiting for the order).

Timeouts and sizes

Caching

• Do not cache catalog answers or sessions on your side either: prices, stock and codes are checked live, and a session can change under your copy (the buyer's order completes it, expiry cancels it).
• Answers carry an ETag: strong as the API sends it, and weak (W/"…") when the web server compresses the answer, which it does when you send Accept-Encoding: gzip. A GET that sends If-None-Match with the current ETag, in either form, is answered 304 Not Modified without a body, even though the answer is no-store; if your HTTP library adds If-None-Match by itself, handle the 304. Writes never answer 304.
• No proxy between you and the API caches UCP answers.
• A merchant's change — UCP switched on or off, the storefront or its key switched off, a domain removed — applies at once. A newly added domain is served once its DNS is verified and its certificate is active, and then within 30 seconds. Your copy of the profile can be up to 5 minutes old.
• The shop caches your platform profile for its max-age, clamped to 60 seconds – 1 hour (5 minutes without one). A change to your profile — a new capability, a corrected version — takes effect after that copy expires: the first request after it is still answered from the old copy while the shop fetches the new one in the background. If that fetch fails, the old copy stays in use until an hour after it expired, and the fetch is retried at most once a minute.

Session lifetimes

GET, complete and cancel never extend a session. expires_at in every answer is the deadline in UTC. Expiry is lazy: nothing happens at the deadline itself; the next request that reads or writes the checkout, or converts its cart again, cancels it. Details in Concepts and lifecycle.

To keep an open checkout alive while the buyer decides, PUT it before expires_at — a PUT of {} prices it again and extends it by 24 hours. Once the buyer has taken it to the shop, nothing extends it.

Waiting for the order

The API sends no webhooks. You learn that the buyer ordered by reading the checkout: GET /ucp/v1/checkout-sessions/{id} returns status: "completed" and order once the order is placed on the shop.

• Hand over a checkout, not a cart: only a checkout becomes completed.
• Interval. The server suggests none. A sensible cadence is every 5–10 seconds for the first quarter of an hour after the buyer got continue_url, then once a minute.
• One request in flight per checkout. Every checkout read waits for the session's turn; on 503 wait Retry-After and go on.
• Stop at completed (read order) or canceled. Stop as well after expires_at: one more read after the deadline gives the final answer — completed if the order came first, otherwise canceled.
• Expect "never completed". A buyer who does not order, signs in on the shop's checkout after a guest handoff, or removes the items leaves the checkout open until it expires; so does, rarely, a completion that failed on Monokaido's side (it is best effort and only logged). The shop's own confirmation is what the buyer sees.
• Poll from any open status. A checkout handed over while incomplete completes with the order too.

import { setTimeout as sleep } from 'node:timers/promises';

// Poll a handed-over checkout until it is completed, canceled or past its deadline.
async function waitForOrder(api, checkoutId, profileUrl) {
  const started = Date.now();
  for (;;) {
    const res = await ucpCall('GET', `${api}/checkout-sessions/${checkoutId}`, { profileUrl });
    if (res.status === 404) return { outcome: 'not_served' };                   // the shop stopped serving UCP: re-discover it later
    if (!res.ok) throw new Error(`HTTP ${res.status}`);                         // retries spent: try again later
    const checkout = await res.json();
    if (checkout.ucp?.status === 'error') return { outcome: 'gone' };            // not_found
    if (checkout.status === 'completed') return { outcome: 'ordered', order: checkout.order };
    if (checkout.status === 'canceled') return { outcome: 'canceled' };
    const pastDeadline = Date.now() > Date.parse(checkout.expires_at);
    const interval = Date.now() - started < 15 * 60_000 ? 5_000 : 60_000;
    await sleep(pastDeadline ? 1_000 : interval);                               // one last read decides
  }
}

import time
from datetime import datetime

def wait_for_order(api, checkout_id, profile_url):
    """Poll a handed-over checkout until it is completed, canceled or past its deadline."""
    started = time.monotonic()
    while True:
        r = ucp_call("GET", f"{api}/checkout-sessions/{checkout_id}", profile_url)
        if r.status_code == 404:
            return {"outcome": "not_served"}  # the shop stopped serving UCP: re-discover it later
        r.raise_for_status()  # retries spent: try again later
        checkout = r.json()
        if checkout.get("ucp", {}).get("status") == "error":
            return {"outcome": "gone"}  # not_found
        if checkout["status"] == "completed":
            return {"outcome": "ordered", "order": checkout["order"]}
        if checkout["status"] == "canceled":
            return {"outcome": "canceled"}
        deadline = datetime.fromisoformat(checkout["expires_at"].replace("Z", "+00:00"))
        past_deadline = datetime.now(deadline.tzinfo) > deadline
        interval = 5 if time.monotonic() - started < 15 * 60 else 60
        time.sleep(1 if past_deadline else interval)  # one last read decides

A checkout's deadline can be a day away. Run polling in a background job that survives restarts — keep the checkout id and the next poll time in your storage — rather than in the request that served the buyer.

Production checklist

• Every write carries an Idempotency-Key, generated once per logical write, stored with it, reused on every retry with the same body.
• Retries follow the table above: at most 5 attempts, Retry-After when given, exponential backoff with jitter otherwise, no retries for other 4xx and for business errors.
• One request in flight per session, never several in parallel: the shop queues at most four behind a running one.
• Your client timeout is 65 seconds, and redirects are not followed.
• Non-JSON answers are handled by status code: 413, 429, 502, 504 from the web server.
• Rate budgets are watched per egress IP and per operation, across every shop you serve: X-RateLimit-Remaining, 429 counts. Steady traffic stays at half of each limit or less.
• Your platform profile has one stable URL, Cache-Control: public, max-age=3600, and is served fast with 200 from a public address.
• Nothing but the business profile is cached, and that for at most 5 minutes.
• Polling runs in the background, stops at completed, canceled or one read after expires_at, and treats "never completed" as a normal outcome.
• Every call is logged with the time in UTC, host, method, path, status, code and your correlation id — the API returns no request id.