Budgets and retries

Two spending controlsCopy Anchor Link

• Key monthly Gem cap: limits the key's completed charges in the UTC calendar month plus outstanding reservations, including reservations from prior months.
• Request maxGems: optional maximum admitted Gem amount for that request. Media uses its authoritative quote; text and video analysis use a conservative maximum. An omitted ceiling does not mean the request is free.

Both are separate from account balance and LLM quota. A request can pass one check and fail another. Reservations reduce available allowance before generation; measured settlement releases unused allowance when it completes. A cap is a limit, not an allocation of Gems to your account.

PRICE_CHANGED rejects a request whose quote or conservative maximum exceeds maxGems. API_KEY_LIMIT rejects a request that cannot reserve more key allowance. Ask before increasing a user's budget.

Stable request identitiesCopy Anchor Link

Every media, text, and extraction submission requires Idempotency-Key: 1–128 characters from ASCII letters, digits, _, ., :, and -.

Persist the identity, exact request body, and originating key before dispatch. One identity belongs to one logical request for that API key. Reusing it with a changed request returns 409 IDEMPOTENCY_CONFLICT. Text's stream setting is part of its identity.

An exact replay of a completed text or extraction request returns the retained response without provider inference or another charge. Media replay returns the existing durable run after current preparation checks; saved media remains accessible through the task GET even if replay preparation now fails. All access still requires valid key/account authorization.

Uncertain outcomesCopy Anchor Link

A lost response, provider timeout, or concurrent request can leave 409 REQUEST_UNCERTAIN. Preserve the original identity and payload. Check an existing task ID, or retry the exact submission with backoff using the same API key and idempotency key. Do not change keys or generate a new identity to retry an uncertain outcome.

A pending text or extraction replay only checks its retained outcome; it never dispatches again. If the reservation stays uncertain, contact support with the request/task ID and time, without sharing the secret. There is no automatic timeout release or public cancellation endpoint. Closing a stream does not cancel provider consumption or settlement.

REQUEST_FAILED means the original claim was definitively released. A new generation requires a new identity and the user's existing spending authorization.

Downloads are separateCopy Anchor Link

If a download fails or a signed output URL expires, read the same task for a refreshed URL and retry the download. Never create a new generation just to retrieve an existing file. Read APIs do not advance generation or perform billing settlement.