Idempotency

​

Which requests take the key

• The seller’s creating and moving posts: POST /sell/drafts, POST /sell/drafts/{draft_id}/publish, POST /sell/deals/{deal_id}/status, POST /sell/deals/{deal_id}/offers, POST /sell/deals/{deal_id}/leads, POST /sell/buyers/{buyer_id}/strikes and POST /sell/reviews/{review_id}/response.
• The seller’s answers to an offer and to an address request: POST /sell/offers/{offer_id}/accept, /decline and /counter, and POST /sell/inquiries/{inquiry_id}/approve and /decline.
• The buyer’s writes: POST /buy/offers, POST /buy/offers/{offer_id}/counter, /decline, /accept and /withdraw, POST /buy/deals/{deal_id}/inquiries, POST /buy/buy-boxes and POST /buy/me/proof-of-funds.
• The webhook endpoints of both sides, POST /sell/webhooks and POST /buy/webhooks.

​

The key

• 1 to 255 characters. Use a UUID, or a key of your own system, for example your record id and the action.
• Scoped to your OAuth client and to the person the token names. The same string from another client or another person is another key.
• Kept 24 hours. After that, the same string starts a new request.
• Stored with a fingerprint of the method, the path and the body. The order of the keys inside the JSON does not change the fingerprint.

​

Replay and the two conflicts

​

The domain rules

• One active deal per property. A second publish on an address with a live deal answers 409 address_unavailable.
• One active chain per buyer per deal. A second submit answers 409 offer_exists, and the body names the open round.
• One inquiry per type per deal per day. The second inquiry, or the second address request, on one deal in 24 hours answers 429 duplicate_inquiry with Retry-After: 86400, and the body names deal_id and type.

​

A retry recipe

import { randomUUID } from "node:crypto";

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

export async function submitOffer(body) {
  const key = randomUUID(); // minted once, before the first send
  for (let attempt = 0; attempt < 5; attempt++) {
    let res;
    try {
      res = await fetch("https://api.investorlift.com/marketplace/v1/buy/offers", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.MARKETPLACE_TOKEN}`,
          "Content-Type": "application/json",
          "Idempotency-Key": key,
        },
        body: JSON.stringify(body),
      });
    } catch {
      await sleep(1000 * 2 ** attempt); // a network fault: same key, same body
      continue;
    }
    if (res.status === 409) {
      const problem = await res.clone().json();
      if (problem.code === "idempotency_in_progress") {
        await sleep(1000 * Number(res.headers.get("Retry-After") ?? "1"));
        continue;
      }
    }
    if (res.status >= 500) {
      await sleep(1000 * 2 ** attempt); // the API released the key
      continue;
    }
    return res; // a 2xx, a replay, or a 4xx to act on
  }
  throw new Error(`no answer after five tries for key ${key}`);
}