Handle idempotency and rate limits
Give each intended write a stable key, replay safely after uncertainty, and back off from explicit limits.
On this page
Network uncertainty must not create duplicate paid work. Send an Idempotency-Key on generation create and retry requests, even though discovery, estimation, and reads do not need one.
A key identifies one intent
Generate a unique, non-secret string for one logical create or retry. Reuse it when repeating that same request after a timeout or lost response. Do not rotate it merely because the response was uncertain.
Reusing the key with the same intent returns the existing generation. Reusing it for a different body returns 409 idempotency_conflict. A retry key identifies the retry itself, not the original create.
Back off from limits
Limits apply to authenticated request volume, generation creation frequency, and concurrent active generations. A rejected request returns 429 rate_limit_exceeded. Do not fan out immediate retries; reduce concurrency and use bounded exponential backoff.
Use one key for one write intent
A key names one create or retry intent. It is not a secret.
Reuse the same key after a timeout with the same intended request.
Changing the request while reusing a key returns a conflict.
Respond to explicit limits
60 / 60sAuthenticated requests per API key.10 / 60sGeneration creates and retries per API key.5 activeConcurrent queued or running generations per organization.A rejected request returns 429 rate_limit_exceeded. Reduce concurrency, use bounded exponential backoff, and keep the original key when replaying the same write intent.