API Error Codes

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.
• Overridable, but the floor is not — a hard fail blocks the launch (preflight_failed) unless a non-empty preflightOverrideJustification is supplied, which records a preflight_override evidence packet. The security floor runs first and is never waived by a preflight override.
• Override = evidence (fail-closed) — if the preflight_override evidence write fails, the deploy is blocked (preflight_override_unaudited, HTTP 503, retryable) rather than proceeding as a silent unaudited bypass.

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 actually reported deploying (manifestDigest, corroborated by the EAD observed-running-digest) against the release’s gated digest.

• verified — reported == gated (deploy-by-digest proven for that target).
• mismatch — reported != gated (a loud drift/tamper finding, carrying a DigestMismatch failure anatomy; non-retryable). Produces no attestation.
• unverified — the agent reported no digest (unobserved) — never a fake verified. Produces no attestation.

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/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.

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 } }

The 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