# Budgets and retries

Keep spending bounded and avoid duplicate generations.

## Two spending controls

- **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 identities

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 outcomes

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 separate

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.