Idempotency

Networks fail. If a submission times out you cannot tell whether Grihafy received it. An Idempotency-Key lets you send the same submission again without creating a second analysis or using a second credit.

How to use it

Generate a unique key for each analysis you intend to create, for example a random UUID. Use 1 to 255 printable ASCII characters.
Send it in the Idempotency-Key header on POST /v1/analyses. The header is required.
Store the key with your own record. If you need to retry, send the exact same request with the same key.

Keys last 24 hours and apply within your organization and key type: a test key and a live key do not share keys.

What happens when you reuse a key

You send	Result
The same key and the same request	The original response is returned with the header `Idempotent-Replayed: true`. No new analysis is created.
The same key with a different file or fields	`422 idempotency_key_reused`. Use a new key for a new analysis.
The same key while the first request is still being handled	`409 idempotency_in_progress`. Wait a few seconds and send it again.
The same key after the first request crashed midway	The key stays locked for about 10 minutes, then the request can be sent again.

Which failures are remembered

Requests rejected before they are accepted (an invalid header or field, a file that is too large or the wrong type) do not use up the key. Fix the request and send it again.
Once a valid submission is accepted, a lasting rejection such as 422 image_unreadable is saved and replayed for the same key. Use a new key for a different image.
Temporary conditions, such as 402 (no credit), 409 (state) and 429 (limits), are checked again on every retry. Retry with the same key after adding credits or waiting for Retry-After.

Keep the request identical when you retry

Send the same file bytes and the same fields. Re-encoding the image or changing a field counts as a different request and returns 422 idempotency_key_reused.

See the error codes and the submit operation.