Idempotency & pagination
Reliable API clients need to handle network retries and large result sets without creating duplicate work or silently missing resources.Idempotency
A network timeout does not prove Starfire failed to create a run, build, or other durable resource. Retrying a state-changing request blindly can create duplicates. Where the active v1 contract supports idempotency:- Generate a stable idempotency value for one logical operation.
- Send it using the documented request mechanism.
- Reuse the same value only when retrying that same logical operation.
- Generate a new value for a genuinely new operation.
- build creation
- long-running run creation
- other expensive/durable create actions
Read before recreating
If an ambiguous failure returns a request/resource ID, check the resource state before creating another copy.Pagination
Large collections such as logs, runs, artifacts, or usage records should be paginated. The active API can use cursor-style or another documented pagination contract. Treat returned continuation values as opaque; do not construct your own cursor by guessing internal IDs.Stable filters
When paging through a collection, keep filters/sort consistent unless you intentionally begin a new listing operation.Changing data
Collections can change while you paginate. For audit/reporting tasks that need a stable time range, filter by timestamps or other documented boundaries rather than assuming the collection is frozen during the listing.Retries and page requests
Read-only page retrieval can generally be retried after temporary failures according to rate-limit/error guidance. Do not restart from page one unless your application actually needs to rebuild the result set.The exact idempotency header/field and pagination response fields belong to the active OpenAPI contract. This page defines client behavior, not an undocumented wire format.