Error handling and retries

Audience: Developers

Error handling and retries

Handle failures and retries for research requests and tasks.

Task status values

Tasks move through states such as:

• PENDING — Queued, not yet started.

• RECEIVED / STARTED — In progress.

• SUCCESS — Completed; fetch result from the task endpoint.

• FAILURE — Error; check error field for details.

• REVOKED — Cancelled.

• RETRY — Retrying after a failure.

Use the SDK to poll until completion or failure: client.tasks.get_status(task_id) or client.taskgroups.get(taskgroup_id).

HTTP and API errors

• 401 — Invalid or missing API key.

• 404 — Task or task group not found.

• 422 — Validation error (e.g. invalid profile, malformed query).

• 5xx — Server or upstream failure; retry with backoff.

See General API Status Codes for a full list.

Retries and idempotency

• Research execution is best-effort; transient failures can be retried by creating a new task.

• Use exponential backoff for 5xx and avoid overwhelming the service. Task creation is idempotent in the sense that each creation yields a new task ID; avoid duplicate business logic by tracking your own request IDs if needed.

Webhook failures

If you use webhooks (e.g. via WebhookConfig in client.tasks.create or client.taskgroups.create), your endpoint may receive retries on failure. Implement idempotent handling (e.g. by task ID) and return 2xx quickly so the service can consider the notification delivered. Check webhook payload docs for signature and payload shape; the SDK README describes signature verification.