Idempotent requests

ORG_ID="7b1e6c1a-3f52-4d0e-9a57-2c8f1e0b4d11"
IDEMPOTENCY_KEY="$(uuidgen)"

# --retry repeats the request on a timeout, a dropped connection or a 5xx.
# Every attempt carries the same Idempotency-Key, so the prompt is created once.
curl --retry 3 --retry-all-errors --max-time 30 \
  -X POST "https://api.surfais.com/v1/orgs/$ORG_ID/prompts" \
  -H "Authorization: Bearer $SURFAIS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "brand_id": "c2a4e8f0-6b1d-4c3a-8e5f-9d7b2a1c4e60",
    "text": "best boutique hotels in Lisbon",
    "countries": ["GB", "IE"]
  }'

import os
import time
import uuid

import requests

BASE_URL = "https://api.surfais.com/v1"
API_KEY = os.environ["SURFAIS_API_KEY"]
ORG_ID = "7b1e6c1a-3f52-4d0e-9a57-2c8f1e0b4d11"
BRAND_ID = "c2a4e8f0-6b1d-4c3a-8e5f-9d7b2a1c4e60"
MAX_ATTEMPTS = 5
MAX_WAIT_SECONDS = 120


def create_prompt(text, countries):
    # One key for this logical operation. Every retry below reuses it.
    idempotency_key = str(uuid.uuid4())
    body = {"brand_id": BRAND_ID, "text": text, "countries": countries}

    for attempt in range(MAX_ATTEMPTS):
        try:
            response = requests.post(
                f"{BASE_URL}/orgs/{ORG_ID}/prompts",
                headers={
                    "Authorization": f"Bearer {API_KEY}",
                    "Idempotency-Key": idempotency_key,
                },
                json=body,
                timeout=30,
            )
        except (requests.ConnectionError, requests.Timeout):
            # The request may or may not have run. The key makes the retry safe.
            time.sleep(2**attempt)
            continue

        if response.ok:
            if response.headers.get("Idempotent-Replayed") == "true":
                print("An earlier attempt had already created this prompt")
            return response.json()["data"]

        error = response.json()
        code = error["error"]["code"]
        # 5xx is never stored, 429 is refused before the write, and in_flight
        # means an earlier attempt is still running. All three are safe to retry.
        retryable = (
            response.status_code in (429, 500, 503)
            or code == "idempotency_key_in_flight"
        )
        wait = int(response.headers.get("Retry-After", 2**attempt))
        if not retryable or wait > MAX_WAIT_SECONDS:
            raise RuntimeError(
                f'{response.status_code} {code} (request {error["request_id"]})'
            )
        time.sleep(wait)

    raise RuntimeError("Gave up after repeated failures")


if __name__ == "__main__":
    prompt = create_prompt("best boutique hotels in Lisbon", ["GB", "IE"])
    print(prompt["id"], prompt["active"])

// Node 18+. Save as create-prompt.mjs and run: node create-prompt.mjs
import { randomUUID } from "node:crypto";

const BASE_URL = "https://api.surfais.com/v1";
const API_KEY = process.env.SURFAIS_API_KEY;
const ORG_ID = "7b1e6c1a-3f52-4d0e-9a57-2c8f1e0b4d11";
const BRAND_ID = "c2a4e8f0-6b1d-4c3a-8e5f-9d7b2a1c4e60";
const MAX_ATTEMPTS = 5;
const MAX_WAIT_SECONDS = 120;

const sleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));

async function createPrompt(text, countries) {
  // One key for this logical operation. Every retry below reuses it.
  const idempotencyKey = randomUUID();
  const body = JSON.stringify({ brand_id: BRAND_ID, text, countries });

  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
    let response;
    try {
      response = await fetch(`${BASE_URL}/orgs/${ORG_ID}/prompts`, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${API_KEY}`,
          "Content-Type": "application/json",
          "Idempotency-Key": idempotencyKey,
        },
        body,
        signal: AbortSignal.timeout(30_000),
      });
    } catch {
      // The request may or may not have run. The key makes the retry safe.
      await sleep(2 ** attempt);
      continue;
    }

    if (response.ok) {
      if (response.headers.get("Idempotent-Replayed") === "true") {
        console.log("An earlier attempt had already created this prompt");
      }
      return (await response.json()).data;
    }

    const error = await response.json();
    const code = error.error.code;
    // 5xx is never stored, 429 is refused before the write, and in_flight
    // means an earlier attempt is still running. All three are safe to retry.
    const retryable =
      [429, 500, 503].includes(response.status) || code === "idempotency_key_in_flight";
    const wait = Number(response.headers.get("Retry-After") ?? 2 ** attempt);
    if (!retryable || wait > MAX_WAIT_SECONDS) {
      throw new Error(`${response.status} ${code} (request ${error.request_id})`);
    }
    await sleep(wait);
  }
  throw new Error("Gave up after repeated failures");
}

const prompt = await createPrompt("best boutique hotels in Lisbon", ["GB", "IE"]);
console.log(prompt.id, prompt.active);