Errors and recovery

Operade returns a stable machine-readable code alongside diagnostic text. Use the code for program logic. Do not branch on or display raw message text: wording and operational context may change without changing the condition.

Symptom#

An API request returns a non-success status, or the dashboard reports that a draft, branch, version, or deployment action could not be completed. A typical response has an error object with code, message, and sometimes details.

Error anatomy#

Read error.code for stable program handling. error.message and error.details are diagnostic: they can contain operational identifiers, configuration names, or field context, and details may be absent. Map known codes to curated UI copy, place reviewed field diagnostics beside the relevant input, and otherwise show a neutral failure message.

Cause#

The general causes are invalid input, missing access, stale state, or an unexpected service failure. Branch and draft operations add optimistic-concurrency checks: the server rejects work based on an older tip or preview instead of silently overwriting newer work.

Verify#

Record the HTTP status, error code, request path, and a timestamp. Inspect message and details only in controlled debugging, and redact operational identifiers, configuration names, and customer content before logging or escalation. For a conflict, refresh the branch, draft, or deployment state before comparing submitted identifiers. Never record an API key, session cookie, Telegram bot token, or Secret value.

Recovery#

Correct validation fields and retry. For stale state, fetch the latest resource, create a new preview when required, review the changed result, and submit the current identifiers. Do not retry internal indefinitely. Use bounded retries only for transient failures and preserve the original operation context.

Escalation#

Escalate when the same request still fails after one clean refresh, an internal response repeats, or recovery would discard authored work. Include only approved non-sensitive identifiers, the UTC time, status, and code. See Support for the approved channels and API errors for the response shape.

Error code index#

• branch_archived — restore the branch before writing.
• branch_force_forbidden — retry without force, or have an admin or owner perform the forced merge.
• branch_invalid — correct the branch state or request.
• branch_lineage_noop — source history adds no change.
• branch_live — an admin or owner must perform protected merge, rebase, or publish actions; remove traffic before archiving.
• branch_name_conflict — choose a unique branch name.
• branch_no_common_ancestor — the branches cannot be combined.
• branch_preview_stale — create and review a new preview.
• branch_protected — have an admin or owner perform the protected action, or unprotect the branch first.
• branch_same_source_target — choose different branches.
• branch_tip_changed — refresh and submit the current tip.
• conflict_stale_draft — reconcile the draft with the latest version.
• conflict_test_revision — reload the Agent Test and submit the current immutable revision identifier.
• cursor_invalid — restart the listing without the bad cursor.
• deployment_branch_archived — restore or remove that branch.
• deployment_invalid — correct the traffic distribution.
• deployment_stale — make the selected live branch point to a published version or fix its invalid configuration before deploying.
• draft_changed — refresh the draft before replacing it.
• draft_exists — reconcile or explicitly handle the existing draft.
• draft_reconcile_incomplete — resolve every reported conflict.
• draft_reconcile_invalid — if the Draft already uses the latest tip, continue without reconciliation because no reconciliation is needed; otherwise correct invalid or conflicting paths or choices. If the reconciled configuration is not an object, choose Draft or Latest values that preserve the configuration object before retrying.
• draft_reconcile_stale — reload the latest draft and tip.
• forbidden — the credential or role cannot perform the action.
• internal — an unexpected server failure occurred.
• invocation_not_ready — wait until every Test Run is terminal before retrying failure bucketing.
• not_found — the resource is absent or outside the workspace scope.
• nothing_to_publish — the draft does not create a new version.
• bucketing_not_retryable — retry failure bucketing only after a failed attempt and when no active bucketing lease owns the work.
• routing_unavailable — production routing has no valid positive traffic distribution to a published Version; publish a Version and configure valid deployment traffic totaling 100 percent.
• user_not_found — the account for that member email does not exist.
• validation_failed — one or more request fields are invalid.

For branch-specific recovery, read Merge and rebase and Reconcile and revert.