Polling - Higgsfield API Docs

Poll the status_url returned by the submission response until the request reaches a terminal state.

Recommended strategy

Start with a two-second interval.
Increase the interval gradually up to ten seconds.
Add random jitter when many workers poll concurrently.
Stop on completed, failed, nsfw, or canceled.
Set an application-level timeout appropriate for the selected model.

import random
import time

import httpx

terminal_statuses = {"completed", "failed", "nsfw", "canceled"}
delay = 2.0

while True:
    response = httpx.get(
        status_url,
        headers={"Authorization": f"Key {key_id}:{key_secret}"},
        timeout=30,
    )
    response.raise_for_status()
    result = response.json()

    if result["status"] in terminal_statuses:
        break

    time.sleep(delay + random.uniform(0, 0.5))
    delay = min(delay * 1.5, 10.0)

Retry decisions

Response	Recommended action
`200` with a non-terminal status	Continue polling with backoff.
`401`	Stop and fix the credentials.
`404`	Stop and verify the request ID and account.
`5xx` or network failure	Retry the status request with exponential backoff.

For long-running production workloads, use webhooks and keep polling as a recovery path.