# 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](/docs/reference/support) for the approved channels and [API errors](/docs/reference/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](/docs/deploy/merge-and-rebase) and [Reconcile and revert](/docs/deploy/reconcile-and-revert).