Idempotency and safe retries

BASE="${FILMO_BASE_URL:-https://app.filmo.io}"
KEY="$(uuidgen)"   # store this with your own record BEFORE the first attempt

for attempt in 1 2 3 4; do
  rm -f headers.txt
  status=$(curl -sS -o response.json -D headers.txt -w '%{http_code}' \
    -X POST "$BASE/api/v1/contacts" \
    -H "Authorization: Bearer $FILMO_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $KEY" \
    -d '{"name":"Acme Rentals","contactType":"company","role":"client","email":"hello@example.com"}') || status=000

  case "$status" in
    2??) break ;;
    500)
      if grep -qi '^idempotent-replay: true' headers.txt; then
        echo "Stored 500: stop and read the resource before doing anything else" >&2
        exit 1
      fi ;;
    409)
      # in_progress or lock_timeout: wait and retry. invalid_state never clears by waiting.
      if grep -q '"invalid_state"' response.json; then
        echo "Conflict with the state of the resource: read it before doing anything else" >&2
        cat response.json >&2
        exit 1
      fi ;;
    000|429|502|503|504) ;;  # 502, 503, 504 without a problem document: treat like a 500, same key
    *) echo "Not retryable: HTTP $status" >&2; cat response.json >&2; exit 1 ;;
  esac

  wait=$(grep -i '^retry-after:' headers.txt 2>/dev/null | tr -dc '0-9')
  sleep "${wait:-$((2 ** attempt))}"
done

case "$status" in
  2??) cat response.json ;;
  *) echo "Gave up (last status $status): read the resource before retrying" >&2; exit 1 ;;
esac

import { randomUUID } from "node:crypto";

const base = process.env.FILMO_BASE_URL ?? "https://app.filmo.io";
const sleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));

// `key` is one UUID per business operation, stored with your own record
// before the first attempt and reused on every retry of that operation.
export async function createContact(body, key) {
  for (let attempt = 0; attempt < 4; attempt++) {
    let res;
    try {
      res = await fetch(base + "/api/v1/contacts", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.FILMO_API_KEY}`,
          "Content-Type": "application/json",
          "Idempotency-Key": key,
        },
        body: JSON.stringify(body),
      });
    } catch {
      await sleep(2 ** attempt); // network failure: retry with the SAME key
      continue;
    }

    if (res.ok) {
      const replayed = res.headers.get("Idempotent-Replay") === "true";
      return { contact: (await res.json()).data, replayed };
    }
    if (res.status === 500 && res.headers.get("Idempotent-Replay") === "true") {
      throw new Error("Stored 500: stop and read the resource before doing anything else");
    }
    if (res.status === 409) {
      const problem = await res.json();
      // "in_progress" and "lock_timeout" clear by waiting; "invalid_state" never does.
      if (problem.errors?.[0]?.code === "invalid_state") {
        throw new Error("Conflict with the state of the resource: " + problem.detail);
      }
    } else if (![429, 500, 502, 503, 504].includes(res.status)) {
      throw new Error("Not retryable: HTTP " + res.status + " " + (await res.text()));
    }
    await sleep(Number(res.headers.get("Retry-After")) || 2 ** attempt);
  }
  throw new Error("Gave up: read the resource before retrying");
}

const { contact, replayed } = await createContact(
  { name: "Acme Rentals", contactType: "company", role: "client", email: "hello@example.com" },
  randomUUID(),
);
console.log(contact.id, replayed ? "(replayed)" : "(created)");

import os
import time
import uuid

import requests

BASE = os.environ.get("FILMO_BASE_URL", "https://app.filmo.io")
AUTH = {"Authorization": f"Bearer {os.environ['FILMO_API_KEY']}"}


def create_contact(body, key):
    """key: one UUID per business operation, stored before the first attempt."""
    for attempt in range(4):
        try:
            res = requests.post(
                BASE + "/api/v1/contacts",
                json=body,
                headers={**AUTH, "Idempotency-Key": key},
                timeout=30,
            )
        except requests.RequestException:
            time.sleep(2**attempt)  # network failure: retry with the SAME key
            continue

        if res.ok:
            return res.json()["data"], res.headers.get("Idempotent-Replay") == "true"
        if res.status_code == 500 and res.headers.get("Idempotent-Replay") == "true":
            raise RuntimeError("Stored 500: stop and read the resource before doing anything else")
        if res.status_code == 409:
            # "in_progress" and "lock_timeout" clear by waiting; "invalid_state" never does.
            cause = ((res.json().get("errors") or [{}])[0]).get("code")
            if cause == "invalid_state":
                raise RuntimeError("Conflict with the state of the resource: " + res.json()["detail"])
        elif res.status_code not in (429, 500, 502, 503, 504):
            raise RuntimeError(f"Not retryable: HTTP {res.status_code} {res.text}")
        time.sleep(float(res.headers.get("Retry-After", 2**attempt)))
    raise RuntimeError("Gave up: read the resource before retrying")


contact, replayed = create_contact(
    {"name": "Acme Rentals", "contactType": "company", "role": "client", "email": "hello@example.com"},
    str(uuid.uuid4()),
)
print(contact["id"], "(replayed)" if replayed else "(created)")