Operations, errors and recovery
Documentation version: 858adedd187db2e94614b1dfd389e4bf98e6e202:ac5d527caaa1f97eee9d71262e7c843ae7b24000e01ba5b44931108b2b489c0d
A successful mutation response commonly returns a durable operation rather than a ready resource. The metadata owner records it atomically with quota, idempotency, audit and outbox state. Native pg-boss delivers work to the existing coordinator; individual modules own their external effects.
Observe one logical request
Persist the idempotency key and request body before submission. Reusing them after a lost response returns the same logical work. Read the returned operation ID through the same scoped management client. Poll only within the caller's explicit observation budget; cancelling a request or closing a browser tab does not undo accepted changes.
succeeded means the operation's native completion checks passed. It is not a
promise that a service can never fail afterward. Inspect current resource and
dependency health separately. A waiting operation requires its dependency or
uncertain effects to be reconciled; automatic retry and manual resume have
distinct native ownership. Consumers cannot rewrite operation phases.
Diagnose without widening access
| Symptom | Safe next action |
|---|---|
| Invalid/expired credential or denied grant | Ask the credential owner to check exact technical scope and current authorization; never put an operator token in the app |
| Revision or idempotency conflict | Read current state and reconcile the original intent before submitting a changed request |
| Quota or unavailable capacity | Inspect the named allocation boundary and allowed capacity profiles; do not silently spill across regions or delete required state |
| Dependency unavailable | Read durable operation/context and current dependency readiness; a timeout is not proof the external effect did not happen |
| Failed candidate readiness | Retain the active release, inspect the candidate's build/runtime output and publish a corrected immutable release |
| Missing raw log output | Distinguish unavailable/expired logs from lost operation history; use retained outcome/context and native recovery receipts |
API error codes and response envelopes are generated in the management reference. SDK transports preserve scoped errors and caller deadlines. Server logs must not include cookies, credentials, full user payloads or arbitrary native diagnostics.
Logs, history and alerts
Use management.operations.logs(operationId, kind) only for the log kinds
declared by that operation owner. A caller cannot select a filesystem path or
another tenant's output. Raw logs expire independently of durable operation,
idempotency and recovery state. Active tasks/releases/recovery references remain
protected during cleanup.
Prometheus evaluates internal resource/dependency conditions. Independent availability probes test user-visible endpoints from another failure domain. The operator dashboard adds resource and incident context; the public status page exposes only approved region/service projections. A public "operational" component is not a statement that every private host measurement is healthy.
Rollback and restore
A compatible application rollback selects a retained immutable release through the same readiness/routing owner. It does not undo database migrations, user writes or external task effects. Jobs are at least once; use the provided stable effect key with idempotent downstream services.
Whole-installation recovery belongs to the infrastructure operator and requires independent state, trust/key custody, fencing and functional readback. A tenant export is a separately scoped format. The tested cold Shared recovery profile permits interruption and post-checkpoint loss. Continuous customer HA, other providers, offline installations and other untested profiles remain unavailable. Operators use the protected recovery procedure.