> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Retry a submission without creating a second job.

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.

```bash theme={null}
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](https://docs.blon.ai/how-to/workflows.md).

`POST /estimate` ignores the header: an estimate creates nothing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.