API errors and reliable integrations
Response codes
| Code | Meaning | Action |
|---|---|---|
| 200 / 201 | Completed / resource created | Read the response body |
| 202 | Accepted into a queue | Check the operation by its ID |
| 401 | Missing, expired, or revoked key; owner lost access | Check the key and membership |
| 402 | Insufficient budget or plan limit reached | Read the reason and workspace limits |
| 403 | Insufficient rights, read-only key, or 2FA required | Check the role and key settings |
| 404 | Object not found or inaccessible | Check the workspace and ID |
| 410 | File expired or removed from storage | Prepare a new export |
| 422 | Invalid fields or an action unavailable in this state | Read message, code, and errors |
| 429 | Request rate exceeded | Wait for Retry-After |
| 5xx | Temporary server problem | Retry reads with increasing delay |
A typical error contains a human-readable message and a machine-readable code. Validation errors also include field-specific errors. Do not build your integration around the wording of a message.
Limit errors explain which resource is unavailable. A positive balance does not remove caps on the number of sites or concurrent tasks, or enable spending beyond the configured budget. See how limits work.
Pagination
Most lists use page and per_page, returning data and page metadata. Not every endpoint follows that pattern: export history uses limit, while the direct catalog endpoint uses a cursor. Follow each method's contract rather than assuming a shared envelope.
For runs, per_page is at most 100; filters include site_id, schedule_id, status, trigger, and include_trials. For proxies, per_page is at most 200 and pool_id filters the pool. Export history supports limit up to 100.
Retries and timeouts
Retry GET requests with increasing delays and a small random variation. Do not retry authorization or validation failures indefinitely. A POST starting a run may have succeeded just before a connection broke: check history before sending it again.
Polling a long run every millisecond is unnecessary; every 3–5 seconds is usually enough. Stop after a final state. Limit retries and report the rejection reason to an operator.
Deletion
DELETE may affect related data. Save needed results and verify the ID before deleting. A read-only key blocks all POST, PUT, PATCH, and DELETE methods, even commands that do not save data, such as source validation.