Handle errors, retries, and background work

Start with the HTTP status, response headers, and structured problem code. Keep enough state to identify the logical request and the resource it targets.

Retry a read

For transient network failures or 503, retry a safe read after an increasing delay. Honor Retry-After when present. Limit the number or duration of automatic retries and expose the unresolved state to your application.

Authorization and validation failures require correcting credentials, access, or input. Refresh a changed workspace before continuing scoped reads.

Retry a write

When the endpoint supports Idempotency-Key, generate a key once for the logical request. Preserve it with the request inputs and reuse it for recovery. Choose a new key for a separate intended action. Each endpoint defines its own key format and retention behavior.

A lost response can leave the server state uncertain. Read the relevant resource or recorded result before submitting another write. When an endpoint lacks an idempotency contract, reconcile the current state and obtain a fresh revision before deciding to resubmit.

Resolve a revision conflict

1. Read the latest resource and its revision.
2. Compare the current configuration with the change your integration intended.
3. Reconcile conflicting edits.
4. Submit the reviewed change with the new If-Match value.

Keep revisions scoped to their resource. A stream revision, notification approval revision, and workspace revision protect different state.

Follow background work

Search jobs, image analyses, cleanup jobs, and imports expose different state models. Store the returned ID and use that resource’s documented read operation. Treat a successful submission as acceptance and check the resulting state to determine completion.

For stream commands, inspect stream runtime state after acceptance. The contract exposes an operations snapshot for aggregate status.

Cancel work through its documented cancellation or action endpoint when that workflow supports it. Preserve terminal failure information and partial-result coverage in your application.

See Errors and status codes for the problem envelope and status-specific handling.