Reliability - Katalo API

Replay-safe writes

Every write endpoint requires an Idempotency-Key. Reusing the same key with the same payload is safe. Reusing it with a different payload is not.

Behavior	Result
Same key, same payload	Returns the original job instead of creating a duplicate write.
Same key, different payload	Returns `409 idempotency_conflict`.
Retention window	Idempotency records are retained for 24 hours.

Rate limits and concurrency

The API applies layered limits per key, per organization, and in some cases per IP. Limit checks happen before expensive work starts.

Route	Limit
`POST /api/v1/source-assets`	Per-key and per-organization write limits.
`GET /api/v1/source-assets/{ingest_id}`	Read limits for polling source ingest state.
`POST /api/v1/generations`	Per-key and per-organization write limits.
`GET /api/v1/generations/{job_id}`	Read limits for polling and recovery.
`POST /api/v1/generations/{job_id}/regenerate`	Write limits plus organization in-flight job caps.
`GET /api/v1/usage/summary`	Read limits for reporting.
`GET /api/v1/billing/events`	Read limits for ledger export.

The organization-wide in-flight cap is 50 simultaneous generation jobs.

Retry strategy

Retry 429 responses after at least the advertised retry_after value.
Retry retryable 5xx responses with exponential backoff and jitter.
Keep the same idempotency key when repeating the same write.
Do not blindly retry validation, authorization, entitlement, or idempotency conflict errors.

Signed URLs are temporary

Returned output URLs are intentionally short-lived. API responses also send Cache-Control: no-store so clients always read fresh job and billing state. Re-read the job if a signed output URL has expired. Do not assume the first URL returned for a job remains valid for the lifetime of your workflow.