The contract

Idempotency

Send an Idempotency-Key header on POST /v1/predict and a retry can never charge you twice. This page is the whole contract — each statement below is a promise.

The seven promises

The header is optional, and absence is never an error. A request without an Idempotency-Key is processed normally and charged per call. Nothing about the request changes except that a retry of it is a new, charged request.
Keys are scoped to your Account. One Account can never replay another Account's result, whatever key it sends. Two Accounts using the same key value never touch each other.
The replay window is 24 hours. Send the same request with the same key inside the window and you receive the stored response — one Spend, however many sends. After 24 hours the stored response expires, and a repeat is a new, charged request.
Only successful responses are stored. A failed request — one that was refunded — is not stored against its key. So retrying the same key after a 502 or a 504 is a genuine fresh attempt: it spends again, and it can succeed. This is what makes retry-after-a-5xx work; a stored failure would replay the failure.
The same key with a different body is a conflict, not a replay. The request is refused as 422 idempotency-key-conflict and nothing is charged. Send the changed request with a new key.
An identical request already in flight is answered, not raced. While the first send is still being processed, an identical second send receives 409 duplicate-request-in-flight with a Retry-After header, and nothing is charged for it. Wait the interval, ask again, and you get the stored result of the first send.
Zero-cost endpoints ignore the header entirely. POST /v1/validate consumes no Credits and makes no Ledger call, so there is no Spend for a key to protect — an Idempotency-Key sent to it is ignored.

Why this API never retries for you

No request is ever retried on our side. A Metered Call can consume a Credit before it fails, so a gateway that re-issued requests on its own could charge twice for one intent. Retry belongs to you, and the Idempotency-Key is what makes it safe.

Last modified on August 11, 2026

Reading a score

The seven promises

The header is optional, and absence is never an error. A request without an Idempotency-Key is processed normally and charged per call. Nothing about the request changes except that a retry of it is a new, charged request.

Keys are scoped to your Account. One Account can never replay another Account's result, whatever key it sends. Two Accounts using the same key value never touch each other.

The replay window is 24 hours. Send the same request with the same key inside the window and you receive the stored response — one Spend, however many sends. After 24 hours the stored response expires, and a repeat is a new, charged request.

Only successful responses are stored. A failed request — one that was refunded — is not stored against its key. So retrying the same key after a 502 or a 504 is a genuine fresh attempt: it spends again, and it can succeed. This is what makes retry-after-a-5xx work; a stored failure would replay the failure.

The same key with a different body is a conflict, not a replay. The request is refused as 422 idempotency-key-conflict and nothing is charged. Send the changed request with a new key.

An identical request already in flight is answered, not raced. While the first send is still being processed, an identical second send receives 409 duplicate-request-in-flight with a Retry-After header, and nothing is charged for it. Wait the interval, ask again, and you get the stored result of the first send.

Zero-cost endpoints ignore the header entirely. POST /v1/validate consumes no Credits and makes no Ledger call, so there is no Spend for a key to protect — an Idempotency-Key sent to it is ignored.