Errors & Idempotency
Problem responses, retries, rate limits, and duplicate prevention.
Errors use application/problem+json with a real HTTP status and request_id.
Create requests require Idempotency-Key with 8-128 letters, numbers, ., _, :, or -. The API stores only an HMAC of the Key plus a request fingerprint.
- Same key and body returns the original task.
- Same key with a different body returns
409 idempotency_conflict. - An original request still running returns
409 request_in_progresswithRetry-After. - Never generate a new key inside an automatic retry.
Common codes include invalid_api_key, invalid_api_key_rate_limited, api_key_expired, insufficient_scope, validation_error, unsupported_model, unsupported_parameter, input_url_not_allowed, insufficient_credits, payment_required, real_person_not_enabled, rate_limit_exceeded, concurrency_limit_exceeded, provider_unavailable, and service_unavailable.
Repeated invalid credentials from the same client IP are throttled. The service stores only a peppered fingerprint of the IP address and returns invalid_api_key_rate_limited with Retry-After after the configured limit.
Retry network failures, 429, and 503 with backoff, the same body, and the same idempotency key. If the Provider outcome cannot be confirmed, the API intentionally refuses blind resubmission and may hold the concurrency lock until it expires or the task is reconciled.