API Error Codes

Destination currency (source-verified 2026-10-07 at f9dbf896333339ed6ed3e655d4e8e3a793cc38fe): Evidence hosts attestation, canonical-record, capsule, and signing-key reads under /api/evidence/v1; OfflineKit hosts the standard export API under /api/offlinekit/v1/exports. The owner handler suffix determines the complete path. See Evidence architecture. This documentation update does not verify a live signing, promotion, or export operation.

Overview

All API errors follow a consistent format with error codes for programmatic handling.

Error Response Format

interface ApiErrorResponse {
  success: false;
  error: {
    code: string;           // Machine-readable error code
    message: string;        // Human-readable message
    details?: object;       // Additional context
    validationErrors?: ValidationError[];
  };
  meta: {
    requestId: string;
    timestamp: string;
  };
}

interface ValidationError {
  field: string;
  message: string;
  code: string;
}

Error Code Categories

Authentication Errors (401)

Permission Errors (403)

Validation Errors (400)

Resource Errors (404, 409)

Environment Errors (422)

Release Errors (422)

Promotion Errors (422)

Deployment Errors (422)

Deployment Failure Anatomy (execution failures)

The error codes above are pre-deploy 4xx API responses. Once a deploy passes gating and a deployment job runs, an execution failure is described by a structured failure anatomy attached to the job and to each failed target — not a raw exception string. It is surfaced on the deployment DTO (GET /api/v1/release-orchestrator/deployments/{id}) both job-level (failureAnatomy) and per-target (targets[].failureAnatomy), and rendered in the console deployment monitor.

interface DeploymentFailureAnatomy {
  stage: string;        // where it failed: artifact-generation | bundle-assembly | strategy-planning
                        //   | traffic-gate | preflight | execution | health-probe | retry-prep | rollback
  category: string;     // typed cause (see below)
  reason: string;       // stable machine-readable slug
  plainReason: string;  // operator-facing one-line cause (the lead)
  detail: string;       // the raw technical string (exception "TypeName: message"), preserved verbatim
  action: string;       // plain-language remediation guidance
  actionPath: string | null; // a real endpoint to act on, or null (never a dead link)
  retryable: boolean;   // true ONLY for genuinely transient causes
}

Categories: SecretResolution, RegistryUnreachable, AgentUnassigned, AgentOffline, Timeout, TargetNotFound, UnsupportedTarget, NoHealthyTargets, DependencyGraph, PreflightFailed, HealthCheckFailed, NoTargetsEnrolled, StrategyPlanIncomplete, StrategyGateHalted, RollbackNotEligible, Unclassified.

Honesty invariants (binding):

• No fabricated cause — an unrecognized exception/reason maps to Unclassified (generic action), never a mislabeled specific category.
• Detail is never lost — the raw exception type + message is preserved verbatim in detail; the plain reason leads, the detail is demoted-but-reachable. The legacy failureReason (job) / error (task) strings stay populated with the plain reason for back-compat.
• retryable is earned — true only for Timeout, RegistryUnreachable, AgentOffline; every content failure (preflight, health-check, secret, unsupported target, …) and Unclassified is false.
• Absent anatomy (jobs created before this contract) → the DTO fields are null and the console falls back to the raw string (no fabricated stage/category).

Deployment Preflight (pre-launch readiness)

Before a deploy launches, a preflight runs a tri-state readiness checklist (GET /api/v1/release-orchestrator/releases/{releaseId}/deploy-preflight?environmentId=), and the launch chokepoint enforces it after the un-waivable security floor.

interface PreflightReport {
  releaseId: string; environment: string | null;
  armed: boolean;            // true iff zero hard fails (unknowns do NOT dis-arm)
  hasHardFail: boolean;
  failedCheckKeys: string[];
  checks: PreflightCheck[];
}
interface PreflightCheck {
  key: string;               // digest-pinned | image-resolvable | target-ready | secret-resolvable
  title: string;
  status: 'pass' | 'fail' | 'unknown';
  detail: string;
  anatomy: DeploymentFailureAnatomy | null;  // present on a fail (reuses the D1 anatomy shape)
}

Honesty invariants (binding):

• Tri-state, never a false pass — a check that cannot determine its answer (registry unreachable, probe threw, GUID-keyed context unavailable) returns unknown, never pass. unknown is surfaced but never a lone hard block; only a definitive fail blocks the launch.
• Hard failures are not bypassable — a definitive fail blocks the launch (preflight_failed) until the readiness problem is resolved. The former unsigned preflightOverrideJustification path was retired; it is not equivalent to the signed gate-exception flow.
• The scanner-pass floor is independently un-waivable — it runs before preflight enforcement, and a signed gate exception cannot turn an absent or failing scanner verdict into a deploy.

target-ready — current target readiness. The check reads the environment’s current topology (never a recorded deployment). The deploy engine runs only on targets whose stored health is Healthy (ITargetRegistry.ListHealthyAsync in DeployOrchestrator.StartAsync) and needs an active agent on them, so the check separates these outcomes, each with its own reason and next step. Every detail names each relevant target’s health and its last health-check time, or states that no health check is recorded.

The 15-minute freshness window matches the topology projection’s health-check TTL over the default 5-minute readiness-scheduler cadence. Before CCP-007 the check passed on any target with an active agent, regardless of stored health, while the deploy engine then refused the launch with NoHealthyTargets.

Landing Verification & Deployment Attestation (post-deploy)

After a deploy completes, the pipeline verifies the landing and — only on a fully-verified landing — emits a deployment attestation. Both surface on the deployment DTO (landingVerification job-level + targets[].landing per-target; deploymentAttestationRef when attested) and light the console custody Deploy step.

Landing verdict (per target, honest tri-state): compares the digest the agent reported deploying (manifestDigest) against the release’s gated digest. DeploymentLandingVerifier also accepts an independently observed running digest per target as corroboration (observedDigest), but the deployment pipeline (DeploymentEnginePipeline.ApplyLandingVerificationAsync) does not supply one today, so observedDigest is null and a verified result rests on the agent report alone. That is the accepted trust model: a matching agent report is verified without an independent observation.

• verified — every digest held for the target (the agent report and, when supplied, the observation) equals the gated digest (deploy-by-digest proven for that target under the agent-report trust model).
• mismatch — a held digest differs from the gated digest, including an observation that contradicts a matching agent report (a loud drift/tamper finding, carrying a DigestMismatch failure anatomy; non-retryable). Produces no attestation.
• unverified — never a fake verified, for one of three reasons: the agent reported no digest and none was observed; no gated digest is recorded to compare with; or the result covers no targets (overall status only). Produces no attestation.

The verdict carries no observation timestamp.

Console presentation (deployment detail). The Web client normalizes overallStatus and each verdict status at its boundary: only verified, mismatch and unverified pass through; any other value (another spelling, a stored value such as pending, a number, or no status) becomes unknown, and the owner value is quoted rather than interpreted. Only allVerified: true counts as the all-verified claim. The badge, explanation, evidence source and attestation link all come from one state:

In any state other than Verified, a recorded deploymentAttestationRef stays visible as a reference, but the Chain-of-Custody link is not offered.

Deployment attestation (binding honesty): a deployment-kind in-toto attestation (predicate https://stellaops.dev/predicates/deployment@v1) is signed and anchored in the transparency log only when the job is Completed AND every target landed verified. The honesty gate returns before touching the signer/submitter otherwise. It lights custody Deploy = SIGNED (recorded) → PROVEN (verified via POST /api/evidence/v1/rekor/verify, the same path the Scan step uses). Absent a real attestation, Deploy stays RECORDED/MISSING — never a fabricated PROVEN. Signing/submission failure is fail-open (the deploy already succeeded): the landing verdict is still recorded, just without an attestation ref.

Deployment Strategy Plan (honesty preview)

A deployment strategy (rolling / all_at_once / blue_green / canary) is a target-batching planner. GET /api/v1/release-orchestrator/releases/{releaseId}/deploy-plan?strategy=&environmentId= previews what the requested strategy will actually do for a release’s real target count — it runs the strategy’s real plan and returns the phases verbatim plus honest caveats, so a requested strategy never implies behaviour it will not deliver.

{ "strategy": "canary", "requestedStrategy": "canary", "targetCount": 1,
  "phases": [ { "index": 0, "targetCount": 1, "kind": "all-at-once" } ],
  "effectiveBehaviour": "With 1 target, 'canary' runs as a single all-at-once deploy …",
  "caveats": [ "single-target-collapse", "no-traffic-management" ] }

Honesty invariants (binding):

• Phases equal the real plan — copied verbatim from the strategy’s PlanAsync; no idealized/fabricated phases.
• single-target-collapse— with a single target, canary/blue-green/rolling all reduce to one batch of one; the effective behaviour is reported as a single all-at-once deploy and the phase is labeled all-at-once, never a phased-canary illustration.
• no-traffic-management— canary/blue-green do phased target rollout, not traffic-splitting; traffic cutover is external/not automated by the adapter. The preview says so; the UI never implies an automated traffic canary/cutover.
• cannot-preview — an unknown/unresolvable target count returns { "cannotPreview": true, "reason": … }, never a fabricated plan.

The preview is a current calculation, not a recorded plan. It runs over the environment’s healthy target count at request time with the default strategy options. A deployment record’s targets were recorded when that deployment started (LibraryDeploymentRequestStarter persists the environment’s targets at creation; the terminal and in-flight mirrors update those recorded targets and never re-resolve topology). The two have different identities and times.

Console presentation (deployment detail, Flight plan tab). The tab shows two separately labeled sections:

• Recorded rollout — the strategy, start time and every target the deployment recorded, with each target’s recorded status, failure reason, landing result and latest recorded time. A target later removed from the environment stays listed; a topology change does not alter the section or the landing result.
• Current environment (calculated now) — the target-ready result of a fresh preflight (read when the tab opens) with its readiness class, the owner’s reason, the next step and a handoff (Topology & hosts at /ops/platform-setup to enrol a target or assign an agent; the environment’s target inventory for target health), followed by the current plan preview. No recorded target is placed into a calculated phase. When the calculated target count differs from the recorded one, the section says so. A cannot-preview reason is quoted with a handoff to Topology & hosts.

The deployment header shows the latest progress time the record holds (its start and each recorded target start or end) and how current it is: recent, stale (a non-terminal record without recorded progress for more than 12 hours, the deployment-scope bound in the runtime contract), unknown (no usable time, or a latest progress time later than the console clock; an unset owner timestamp such as 0001-01-01 is not a recorded time) or final (terminal status). A stale or unknown record keeps its owner status; no completion or failure is inferred from elapsed time. The header’s time span is measured only from recorded times: Duration for a terminal record (recorded start to recorded end), Elapsed since start otherwise (recorded start to now). When the start or a terminal record’s end is not recorded, the end is earlier than the start, or the start is later than the console clock, the header states that instead of showing a value; the Flight plan tab likewise states that no start time is recorded. A record without any target states that it delivered nothing, whatever its status, with a handoff to target enrolment.

Watch / Drift (post-landing)

After landing, the deploy is watched: deploy agents report the container image digests they OBSERVE running, and the orchestrator compares them against the release’s approved/deployed digests. Tenant-scoped status, drift, and digest-location reads (GET /api/v1/release-orchestrator/estate/status|drift and GET /api/v1/release-orchestrator/estate/digest/{digest}) accept either release:read or orch:read; deviations and the other Estate reads remain orch:read-only.

// GET /estate/status
{ "deployedComponents": 8,
  "drift": { "total": 1, "drift": 1, "inSync": 0, "unobserved": 0, "observingAgents": 1 },
  "deviations": { "count": 0, "subjects": 3, "unevaluated": 1, "unknown": 0, "unbaselined": 0 } }

deviations.count is the number of outstanding estate-finding deviations: deployed (environment, release) subjects whose latest re-evaluation is more severe than the decision that authorized them. A standing regression counts once, and a release that recovered or was replaced does not count. deviations.subjects is the number of deployed (environment, release) subjects; unevaluated (not re-evaluated yet), unbaselined (no authorizing decision with a pass or failure outcome to compare against) and unknown (the re-evaluation reached neither a pass nor a failure) count the subjects whose current risk is not established.

Outstanding deviations surface in the console through the chain-of-custody read: the Watch stage of a running digest whose release has an outstanding deviation is unverifiable (estate-deviation), and the Compliance view’s assurance queue lists those digests first; a subject whose current risk is not established reads unavailable, never clean. The Doctor check check.release.environment.matches-approved fails on count or unbaselined and warns on unevaluated, unknown or an absent classification.

The drift signal surfaces in the console as a needs-you “components in drift” item, an estate-matrix drift chip, and the custody Run-stage rail.

Honesty invariants (binding):

• unobserved is never inSync— a component no agent is reporting is uncovered/unknown, never rendered green. The Run rail shows honest observing-agent coverage; it never claims “healthy” for an unobserved estate.
• Drift is a real deviation, shown loudly — a running digest that is not an approved/deployed digest (drift) is an alarm (unapproved or altered image), never suppressed.
• No fabricated all-clear — observingAgents == 0 → honest no-signal (not a fake green); a read failure → “couldn’t check”, never a fabricated in-sync or fabricated drift.

Gate Errors (422)

Agent Errors (422)

Integration Errors (422)

Workflow Errors (422)

System Errors (500)

Example Error Responses

Validation Error

{
  "success": false,
  "error": {
    "code": "VAL_REQUIRED_FIELD",
    "message": "Validation failed",
    "validationErrors": [
      {
        "field": "releaseId",
        "message": "Release ID is required",
        "code": "VAL_REQUIRED_FIELD"
      },
      {
        "field": "targetEnvironmentId",
        "message": "Invalid UUID format",
        "code": "VAL_INVALID_UUID"
      }
    ]
  },
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2026-01-10T14:30:00Z"
  }
}

Permission Error

{
  "success": false,
  "error": {
    "code": "PERM_SOD_VIOLATION",
    "message": "Separation of duties violation: requester cannot approve their own promotion",
    "details": {
      "promotionId": "promo-uuid",
      "requesterId": "user-uuid",
      "approverId": "user-uuid",
      "environmentId": "env-uuid",
      "requiresSoD": true
    }
  },
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2026-01-10T14:30:00Z"
  }
}

Gate Block Error

{
  "success": false,
  "error": {
    "code": "GATE_SECURITY_BLOCKED",
    "message": "Promotion blocked by security gate",
    "details": {
      "gateName": "security-gate",
      "releaseId": "rel-uuid",
      "targetEnvironment": "production",
      "violations": [
        {
          "type": "critical_vulnerability",
          "count": 3,
          "threshold": 0
        }
      ]
    }
  },
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2026-01-10T14:30:00Z"
  }
}

References

• API Overview
• Security Overview