Idempotency
POST /v1/jobs accepts an optional Idempotency-Key header (Stripe-style) so retries on network errors and 5xx responses cannot create duplicate jobs.
The Idempotency-Key header#
Send a unique Idempotency-Key header on POST /v1/jobs. Replaying the same key within the TTL returns the original job instead of creating a new one. This makes the call safe to retry: if a request times out or returns a 5xx, retry with the same key and you get back the job that was already created (if one was) rather than a duplicate.
curl -X POST https://api.lirovo.ai/v1/jobs \
-H "Authorization: Bearer $LIROVO_API_KEY" \
-H "Idempotency-Key: 2f5c9a1e-0b3d-4a77-9c21-6e8f4d2b1a90" \
-H "Content-Type: application/json" \
-d '{
"source_uri": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"schema_id": "sch_a1b2c3"
}'24-hour TTL#
Idempotency reservations are kept for 24 hours. Within that window, the same key always resolves to the same job. After the TTL expires the key is forgotten, so reusing it later starts a fresh reservation.
Conflict codes#
Two error codes surface idempotency edge cases, both with HTTP status 422.
IDEMPOTENCY_KEY_CONFLICTis returned when a key is reused with a request body whose canonical hash differs from the first call. Use a new key per distinct request.IDEMPOTENCY_KEY_ORPHANEDis returned when a reservation exists but the original job is gone (a race with cleanup, or a prior failed dispatch that left a stale row). Retry with the same key: the route self-heals.