Idempotency - Blon

A network timeout leaves you not knowing whether a job was created. Send an Idempotency-Key header with POST /jobs and you can safely send the same request again.

curl https://api.blon.ai/v1/jobs \
  -H "Authorization: Bearer $BLON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model":"gpt-image-2","input":{"prompt":"A ceramic teapot on a linen table, soft morning light"},"webhook_url":"https://example.com/hooks/blon","metadata":{"order":"A-17"}}'

Rules

The key is 1–255 visible ASCII characters. A UUID works well.
Keys are scoped to the API key that sent them.
Same key, same body: you get the original job back with idempotency_hit: true, whatever its status.
Same key, different body: 409 idempotency_conflict. Use a new key for a new request.
On a timeout, a 5xx marked retryable, or a 429, retry with the same key.

The header is optional on POST /jobs but recommended. It is required when you start a workflow run. POST /estimate ignores the header: an estimate creates nothing.