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
| Status | What happened | What to do |
|---|---|---|
| 400 / 422 | The request or file is invalid. | Correct the request or the unsupported file format, then send it again. |
| 401 | The key was not accepted. | Check the key, its environment and its expiry. Revoked keys cannot be reused. |
| 403 | The key is not allowed to do this. | Check its permissions, your organization membership and account eligibility. |
| 404 | Nothing you can access has this ID. | Check the identifier and its owner. Resources you cannot access also look missing. |
| 409 | The batch body changed, or the configuration revision is stale. | Resolve the difference first. Do not resend unchanged. |
| 429 | Your organization passed its request limit. | Wait for the Retry-After time. The budget is shared by every caller. |
| 5xx / network error | The 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.
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.