Errors and retries

What each status code means, which requests are safe to send again, and the limits every caller in your organization shares.

Status codes

API errors and recovery
StatusWhat happenedWhat to do
400 / 422The request or file is invalid.Correct the request or the unsupported file format, then send it again.
401The key was not accepted.Check the key, its environment and its expiry. Revoked keys cannot be reused.
403The key is not allowed to do this.Check its permissions, your organization membership and account eligibility.
404Nothing you can access has this ID.Check the identifier and its owner. Resources you cannot access also look missing.
409The batch body changed, or the configuration revision is stale.Resolve the difference first. Do not resend unchanged.
429Your organization passed its request limit.Wait for the Retry-After time. The budget is shared by every caller.
5xx / network errorThe outcome is unknown.Retry with bounded backoff. For batches, keep the same body and Idempotency-Key.

A successful batch request can still contain failed surveys. Always read each item’s error_code.

Retry a batch safely

After a lost response or a temporary server failure, resend the same body with the same Idempotency-Key, with bounded backoff. The API reuses the runs it already accepted and recovers any item still waiting for admission.

Never generate a new key because a request timed out. A new key creates new runs and can charge you twice.

An item waiting for admission may need that identical resubmission; polling alone does not resume it.

Retry a failed survey

Once an item has definitively failed and you have fixed the cause, submit only that item in a new batch with a new key. This creates a new run and can consume credits. Do not resubmit items that succeeded.

The retry guarantee covers batch submission only. Uploads and project or configuration writes are not idempotent: after an unknown outcome, check what exists before you create it again.

Limits

Request rate
60 API requests per minute per organization, shared across all keys.
Batch size
1–10 distinct projects.
JSON body
1 MiB. File bytes go directly to storage, not through the API.
Polling
Every 5–10 seconds is enough.
Capacity
Bulk submission does not bypass processing capacity or billing limits.

The Python SDK applies these retry rules for you.