# Failure codes

Every failure the platform reports carries a **stable code**. Branch on the code;
display the message. Messages are written for humans and may be reworded at any
time, codes are an interface and change additively.

Codes appear in two places, with the same meaning in both:

- `status_details.error.code` — why a resource is `failed` or `degraded`
- `findings[].code` from `/diagnose` — everything diagnose correlated

All codes are namespaced by product: `cache.`, `database.`, `queue.`, `vps.`,
`vps-volume.`, `storage.`, `static-site.`, `app.`, `uptime.`, `metric-alert.`,
`serverless.`.

See [Platform automation](platform-automation) for the surrounding contract.

## Universal codes

Emitted for **every** product. `{product}` is the prefix from the list above.

| Code | Severity | Retryable | Meaning | What to do |
|---|---|---|---|---|
| `{product}.healthy` | informational | — | Diagnose found nothing wrong | Nothing |
| `{product}.operation_in_progress` | informational | yes | An operation is still running; diagnose short-circuits rather than reporting a half-built resource as broken | Keep polling `operation.terminal` |
| `{product}.stale_observation` | action_required | yes | An in-flight operation has gone unconfirmed for 15 minutes | Retry the operation; if it repeats, open a ticket |
| `{product}.warnings_recovered` | transient_recovered | — | Warning events occurred and the platform already recovered from them | **Nothing.** Not a current problem |
| `{product}.unknown` | fatal | no | A failure was recorded but could not be classified | Read `message`; open a ticket if unclear |

### Event-derived codes

Where a product exposes cluster events, warnings become findings coded
`{product}.event_{reason}`, with the Kubernetes reason lowercased — so a
`CrashLoopBackOff` on a cache instance is `cache.event_crashloopbackoff`.

These reasons are classified **fatal** — they do not resolve on their own:

| Reason | Code suffix | Typical cause |
|---|---|---|
| `Failed` | `event_failed` | The container or controller reported a failure |
| `FailedCreate` | `event_failedcreate` | The workload object could not be created |
| `FailedScheduling` | `event_failedscheduling` | No node had room, or a volume was not placeable |
| `ErrImagePull` | `event_errimagepull` | The image could not be fetched |
| `ImagePullBackOff` | `event_imagepullbackoff` | Repeated pull failures; usually a bad tag or credential |
| `CrashLoopBackOff` | `event_crashloopbackoff` | The process keeps exiting after start |
| `BackOff` | `event_backoff` | Restarts are being throttled |
| `FailedMount` | `event_failedmount` | A volume could not be attached or mounted |
| `Evicted` | `event_evicted` | The node reclaimed resources |
| `OOMKilling` | `event_oomkilling` | The container exceeded its memory limit |

These are classified **transient_recovered** and are *not* incidents —
Kubernetes emits them during ordinary reconciliation races:

`InternalError` · `UpdateConflict` · `FailedUpdate`, plus any warning whose
message matches a write-conflict pattern (`object has been modified`,
`please apply your changes to the latest version`, `conflict`, `try again`).

Automation that treats every `Warning` event as an outage will page you for
healthy systems. This classification is why `/diagnose` exists rather than
handing you the raw event stream.

## Object storage

| Code | Severity | Retryable | Meaning | What to do |
|---|---|---|---|---|
| `storage.quota_exceeded` | fatal | no | The bucket is at its size limit. **Writes are rejected** while this holds | Delete objects, or raise the limit |
| `storage.quota_nearly_exceeded` | action_required | no | Approaching the limit | Free space before writes start failing |
| `storage.quota_not_applied` | action_required | yes | The bucket exists but the backend did not accept its quota, so **no limit is being enforced** | Retry the update; open a ticket if it persists |
| `storage.usage_stale` | informational | yes | The usage figure is older than 30 minutes | Treat the number as approximate |

Usage is sampled, not live. Quota findings state the age of the measurement they
are based on, because acting on a stale number is how a "you have room" answer
turns into a rejected write.

## Static sites

| Code | Severity | Retryable | Meaning | What to do |
|---|---|---|---|---|
| `static-site.build_failed` | fatal | no | The build command exited non-zero | Read the build logs |
| `static-site.domain_unverified` | action_required | no | A custom domain has no valid DNS record | Add the record shown in the dashboard |
| `static-site.pending_review` | action_required | no | The site is awaiting review before publishing | Wait, or contact support |
| `static-site.suspended` | fatal | no | The site was suspended | Contact support |

## Managed apps

| Code | Severity | Retryable | Meaning | What to do |
|---|---|---|---|---|
| `app.upgrade_failed` | fatal | no | A version upgrade did not complete | Read the logs; the previous version may still be serving |
| `app.upgrade_auto_rolled_back` | action_required | no | An upgrade failed and the platform restored the previous version | **Your app is running.** Investigate before retrying |

`app.upgrade_auto_rolled_back` is deliberately not fatal: the rollback worked and
the app is serving. Reporting it as an outage would be false.

## Serverless containers

These come from correlating the container's status with its live Knative
Revision and Route — two sources that give the wrong answer when read alone.

| Code | Severity | Retryable | Meaning | What to do |
|---|---|---|---|---|
| `serverless.no_pod_scheduled` | fatal | no | The latest revision settled at `Ready=False` with zero replicas: no pod ever started | Fix the image reference or its credential. **The empty log is expected** — nothing ran to write one |
| `serverless.ingress_not_ready` | fatal | no | `IngressReady=False`: the revision is healthy but the public URL does not serve | Check the custom domain and its TLS certificate. Redeploying will not help |
| `serverless.ingress_not_ready` | informational | yes | `IngressReady=Unknown`: the route is still converging | Wait and re-read |
| `serverless.degraded_but_serving` | action_required | no | A new revision failed while an older one keeps serving. **The site is UP** | Do **not** roll back automatically — traffic is already on the last good revision |
| `serverless.replica_count_lagging` | informational | no | `current_replicas` disagrees with the live revision count | Nothing. The container figure is a five-minute cache; the two legitimately differ after a scale-to-zero wake |
| `serverless.revision_data_unavailable` | informational | yes | The Knative Service or Route could not be read, so some checks did not run | Retry. Do **not** read the missing findings as "nothing wrong" |

Two of these are the reason `/diagnose` exists rather than a status field:

- **`no_pod_scheduled` explains an empty log.** Callers otherwise spend a long
  time hunting for output that cannot exist, because the image was never pulled.
- **`ingress_not_ready` separates "deployed" from "reachable".** Every other
  signal — status, revision, events — says the deployment succeeded.

`degraded_but_serving` arrives **alongside** the finding that explains why the
new revision failed — usually `no_pod_scheduled`. Read the whole array: the
first says your site is still up, the second says what to fix.

Revision checks are skipped, and no code is emitted, while an operation is still
running (`operation.terminal` is `false`) and for a stopped container. A healthy
deploy is briefly `Ready=False` with zero replicas, and a stopped container is
*meant* to have no pods; reporting either as a fault would be a false alarm.

## Uptime checks

An uptime failure describes **your target**, not the monitor. A check reporting
`down` is working correctly.

| Code | Severity | Retryable | Meaning | What to do |
|---|---|---|---|---|
| `uptime.dns` | fatal | yes | The hostname did not resolve | Check DNS |
| `uptime.timeout` | fatal | yes | The target did not respond in time | Check load and timeouts |
| `uptime.refused` | fatal | yes | The connection was refused | Check the service is listening |
| `uptime.http_error` | fatal | yes | An unexpected HTTP status | Check the endpoint |
| `uptime.tls_expiring` | action_required | no | The certificate expires soon | Renew it |
| `uptime.tls_expired` | fatal | no | The certificate has expired | Renew it now |
| `uptime.flapping` | action_required | no | The target is alternating up and down | Investigate intermittent failures |
| `uptime.not_running` | informational | no | The check is paused | Resume it |

`retryable: true` here means the *target* may recover, not that re-reading the
check will change anything.

## VPS block volumes

| Code | Severity | Retryable | Meaning | What to do |
|---|---|---|---|---|
| `vps-volume.instance_unavailable` | fatal | no | The parent VPS is stopped or gone, so the volume cannot be attached | Start the instance |
| `vps-volume.awaiting_instance_boot` | informational | yes | The volume is attached and waiting for the guest to see it | Keep waiting |

A volume carries its own `status_details`. Do not poll the parent VM — it stays
`running` throughout an attach and would look like instant success.

## Cache, databases, queues and VPS

These products report failures from two sources:

1. **Recorded failures** — written by the reconciler that observed them, coded
   `{product}.{category}`. The category depends on what the platform observed;
   treat it as opaque and branch on the prefix plus `retryable`.
2. **Event-derived findings** — the `{product}.event_*` codes above.

If you receive a code not listed on this page, apply the general rules: honour
`retryable`, read `message` for the human explanation, and treat an unrecognised
code as a genuine failure rather than ignoring it.

## Envelope errors

These describe the **request**, not the resource, and appear in `error.code`
alongside an HTTP status.

| Code | HTTP | Retryable | Meaning |
|---|---|---|---|
| `{product}.logs_not_supported` | 400 | no | This product has no log surface — check `capabilities.logs` first |
| `{product}.logs_unavailable` | 503 | yes | The log backend did not respond |
| `{product}.events_not_supported` | 400 | no | This resource has no cluster objects to read events from |
| `{product}.events_unavailable` | 503 | yes | Cluster events could not be read |
| `{product}.events_not_permitted` | 503 | no | The platform is not permitted to read events for this resource |
| `operation.not_found` | 404 | no | No operation with that id |
| `registry.no_project` | 400 | no | No project resolved; send `X-Team-Id` |

`events_not_permitted` is separated from `events_unavailable` on purpose: one is
a transient upstream problem worth retrying, the other never resolves by
retrying and needs an operator.

### Registry preflight

`GET /registry/preflight` returns findings rather than failing, so these arrive
with HTTP 200 in `findings[].code`:

| Code | Retryable | Meaning |
|---|---|---|
| `registry.namespace_mismatch` | no | The push target is outside your project's namespace |
| `registry.quota_exceeded` | yes | The push would exceed your storage or repository limit |
| `registry.manifest_not_found` | no | No such tag in the repository — push it first |
| `registry.architecture_mismatch` | no | The image was built for an architecture the platform does not run |
| `registry.no_credential` | no | The image is private and no credential is configured |
| `registry.external_image` | — | Informational: the image is outside your registry, so we cannot verify it |

A 503 with `retryable: true` means an upstream we depend on is unreachable — back
off and retry. A 403 will never succeed with the same token; mint one with the
right ability instead.