Idempotency, Retries, Timeout, and Limits
Idempotency
The Prefill Data Transfer API is idempotent. Each logical prefill submission must include a unique Idempotency-Key header:
Generate a fresh UUID for each new customer prefill session. Do not reuse keys across different customers or different quote journeys.
Scenario | Result
First request with a given key | Payload processed. New record created. recordId and url returned.
Subsequent request with same key and same payload | No new record created. Original recordId and url returned.
Request with same key but different payload | Rejected with 409 Conflict.
Idempotency protects against duplicate records caused by network retries or transient failures. If your request times out and you are unsure whether it succeeded, retrying with the same Idempotency-Key and the same payload is safe.
Retries
Token API: Safe to retry on network errors and 5xx responses. Do not retry on 401 or 403 (fix credentials before retrying). Apply exponential backoff with a maximum retry count (e.g. 3 attempts).
Prefill Data Transfer API: Safe to retry transient failures (5xx, timeouts) when using the same Idempotency-Key and same payload. Do not retry 400 Bad Request (payload is invalid and will fail again until fixed). Do not retry 401 or 403 until the underlying auth or configuration issue is resolved. Retry 429 only after waiting for the Retry-After duration.
Recommended backoff pattern: Attempt 1: immediate. Attempt 2: wait 1s. Attempt 3: wait 2s. Maximum 3 attempts, then surface error to your system.
Timeouts
Standard response times typically fall within our agreed-upon Service Level Agreement (SLA).
Set your HTTP client timeout to at least 10 seconds to avoid premature timeouts on the Prefill API call.
Rate Limits
Rate limiting is enforced on all partner-facing endpoints. Default: 1,000 requests per IP per 60 seconds. Per-partner production limits are agreed during onboarding.
When a rate limit is exceeded:
Implement client-side rate limiting and honor the Retry-After value. Do not implement fixed-interval polling — use adaptive backoff.