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.

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:

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

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

Managed apps

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.

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.

Rapids volumes, backups and restores

The Rapids Volumes API refuses a request with success: false and an error whose code is one of the codes below, with the HTTP status in the table. retryable says whether the same request can succeed later with nothing changed on your side. Branch on the code, never on the message.

Refused because of the account

Not found

The request is wrong

A body that is not valid at all (a field missing, a size that is not a number) is answered 422 with Laravel's {"message": "...", "errors": {...}} instead.

The state does not allow it now

The platform cannot do it now

When a container with a volume does not start

These two arrive in status_details.error.code (and in findings[].code), like the other runtime failures, when the platform cannot start an instance of a container that has a volume.

Uptime checks

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

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

VPS block volumes

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.

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:

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.