Retries and idempotency

Create one Idempotency-Key for each logical POST /requests submission (8–200 characters; a UUID v4 is a good default). Keep that key and the exact JSON body for any retry whose outcome is uncertain. Create a new key for a genuinely new request. Idempotency records are retained for 24 hours; after they expire, reusing a key can create and bill a new submission.

Retry transient transport failures, 429 RATE_LIMIT, and 500/503 responses with bounded exponential backoff and jitter. A 429 CONCURRENCY_LIMIT should wait for active jobs to reach terminal states. A 409 RESULT_NOT_READY is polling, not a new submission. Do not blindly retry validation, authentication, email verification, scope, or expired-result errors.

For an uncertain POST response, retry the exact same body with the same key. A same-key/same-body replay returns charged_tokens: 0 for the replayed operation and idempotent_replay: true; it does not undo the original charge. A same-key/different-body request returns 409 IDEMPOTENCY_CONFLICT; an in-flight duplicate may return 409 IDEMPOTENCY_IN_PROGRESS. Use the clone endpoint or a new key only when intentionally creating a new submission.

Idempotency prevents duplicate submission work and base debits; it does not make the original request free. Set max_credits_per_request when you need a total request budget. See billing for the cap, traffic settlement, CAPTCHA, and refund behavior.

HTML/text results and clone snapshots are retained for seven days. Trace, API-key usage, and audit records are retained for 90 days. See limits for plan limits and errors for retry classification.