Platform API

Idempotency

Send an Idempotency-Key so that a retried POST never starts, or charges for, a second job.

Networks fail. A POST whose response you did not receive may or may not have started a job — and a job costs credits. Send an Idempotency-Key and a retry becomes safe.

Idempotency-Key: <a UUID you generate once per operation>

Rules

Rule	Behaviour
scope	a key is remembered per user and per operation (how long: `GET /v1/meta` `limits.idempotency_key.ttl_seconds`; `null` = as long as its job) (e.g. submitting `image.glam`)
same key, same body	no new job; you get the original handle again (same `job_id`), with the SAME `X-Refabric-Credits` / `X-Refabric-Credit-Type` the first answer carried. Nothing new is held
same key, different body	`409 conflict`, `code: idempotency_key_reused`; nothing runs
same key while the first request is still being processed	`409 conflict`, `code: request_in_progress`, `retryable: true`; retry shortly with the same key
after the retention	the key is forgotten; reusing it starts a new job
format	an opaque string; use a UUID v4

Idempotency is per user: two API keys of the same user share the same key space.

Applies to POST /v1/tasks/{name}. GET, PUT …/cancel and DELETE are naturally idempotent and ignore the header. POST /v1/files ignores it too: registering a url is idempotent on the url itself (the same url answers the same file); a byte upload retried answers a new file.

Recommended use

Generate the key once per logical operation and keep it with the operation (for example in your own job table), not once per HTTP attempt.

import uuid, requests

op_key = str(uuid.uuid4())            # store with your own record
for attempt in range(5):
    try:
        r = session.post(f"{API}/tasks/image.glam", json=body,
                         headers={"Idempotency-Key": op_key}, timeout=60)
        break
    except requests.ConnectionError:
        continue                       # same key → at most one job

curl -s -X POST "$REFABRIC_API/tasks/image.glam" \
  -H "Authorization: Key $REFABRIC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d @body.json