Handle API errors, retries, and concurrency

Interpret problem responses and retry Public API operations without duplicates or lost updates.

RIIW returns structured problem responses for Public API failures. Clients should branch on the stable problem code and HTTP status, retain the request ID for diagnostics, and show the human-readable detail only as supporting context.

Classify responses

Status	Typical meaning	Client action
`400`	Invalid input, scope, cursor, or idempotency header	Correct the request; do not retry unchanged
`401`	Missing, expired, rotated, or revoked token	Refresh OAuth or replace the service-account token
`403`	Missing scope, capability, plan, or valid lifecycle state	Change authorization or plan; do not blind-retry
`404`	Resource absent or outside the credential’s organization	Verify IDs and organization context
`409`	Idempotency, state transition, dependency, or lifecycle conflict	Inspect the problem code and reconcile state
`412`	Stale `If-Match` ETag	Fetch the current resource before deciding again
`429`	Rate limit or quota pressure	Respect `Retry-After` and use bounded backoff
`503`	Temporary integration pause or dependency outage	Respect `Retry-After`; preserve the same logical operation

Use idempotency correctly

Every mutation requires an Idempotency-Key. Generate a high-entropy identifier for one business operation and persist it with the operation state. A network timeout does not justify generating a new key: retry the identical request with the original key.

Reusing a key with a different body, query, method, path, content type, or If-Match value returns a conflict. Completed requests replay their stored response. If a process crashes after the database commit but before an exact response is recorded, RIIW returns non-retryable IDEMPOTENCY_OUTCOME_UNKNOWN rather than risking a duplicate mutation. Reconcile by reading the affected resource or using your deterministic business identifier.

Prevent lost updates

ETags represent monotonically changing resource versions. Preserve the ETag from a read response and send it in If-Match for supported updates and deletes. On 412, fetch the latest state and compare field by field. Do not automatically overwrite another actor’s change.

Project workflow rules remain authoritative. A task status that is valid in one project may be invalid in another, and dependency or parent relationships that create cycles are rejected.

Retry with bounded backoff

Retry only transient network failures, selected 5xx responses, and 429 responses. Use exponential backoff with jitter, a maximum delay, and a total attempt or time budget. Follow Retry-After when present. Keep the original idempotency key for mutations and stop when the response is explicitly non-retryable.

Avoid synchronized polling across customers. Cache stable metadata where appropriate, paginate incrementally, and reduce concurrency after rate-limit responses. Do not retry authentication failures with the same rejected credential.

Operational pauses

INTEGRATION_DISABLED means a platform administrator temporarily paused Public API processing globally or for a selected organization or principal. Credentials remain valid but cannot be used until the pause is lifted. New webhook claims stop while event and delivery records remain preserved.

Applications should display a temporary integration-unavailable state, retain queued local work, and retry only after the indicated delay. Rotating or recreating credentials does not bypass the pause.

Safe diagnostics

Record the request ID, problem code, HTTP status, operation ID, resource ID, and timestamp. Redact bearer tokens, OAuth codes, refresh tokens, webhook signing secrets, raw signatures, and sensitive payload values. If support is needed, provide the smallest reproducible request shape and a redacted response through an authenticated ticket.

Review Authenticate with the Public API for request construction and Configure and verify webhooks for delivery-specific retries.