Implement deterministic errors, complete traversal, bounded polling, and state-aware retries.
Outcome: Implement deterministic errors, complete traversal, bounded polling, and state-aware retries.
400 validation
Correct the request; do not retry unchanged
401 authentication
Stop and repair or rotate the key
403 permission_denied
Review role and resource access
Other 403
Review plan, quota, or entitlement
404 or not found
Verify workspace scope and stable ID
Timeout
Read remote state before repeating a mutation
Other failure
Preserve status and redacted error; retry only when safe
Page-based lists return results and a complete next URL. Follow it until null without rebuilding the URL. Cloud browse returns content and a provider token; resend it as next_token with unchanged browse parameters.
curl --fail-with-body --silent --show-error \
"$UNITLAB_API_URL/api/sdk/projects/PROJECT_ID/upload-sessions/QUEUE_ID/status/" \
-H "Authorization: Api-Key $UNITLAB_API_KEY"Processing is terminal when processing is zero, but failed items can remain. Inspect failed and then read the queue /data/.
Use exponential backoff with jitter for transient reads. Before retrying create, attach, move, action, release, or delete operations, read the target to determine whether the first request succeeded.
Workflow actions and direct moves accept caller-generated idempotency keys. Reuse the same key only when resuming the same logical action.
Execution surface
TLS-verified client using the reviewed current public /api/sdk/... route contract.
Identity
Least-privilege workspace service identity; secrets remain outside code and logs.
Request boundary
URL-encoded stable IDs, explicit deadlines, structured errors, and complete pagination.
Success evidence
Response identifiers, read-after-write verification, and separate processing status for Batch Queues.
Do not infer undocumented private routes. After a timeout, inspect remote state before repeating a mutation.
Related Unitlab capability guides: Unitlab’s data annotation platform