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

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