Errors

Every failure scafo surfaces carries one of twenty-three codes. The code is the stable contract: messages may change, codes may not.

#Problem documents

The node API answers every failure as an RFC 9457 problem document.

HTTP/1.1 409 Conflict
content-type: application/problem+json

{
  "type": "urn:scafo:application-blocked",
  "title": "This application is blocked",
  "status": 409,
  "detail": "\"shop\" has been blocked by an admin of this fleet: it is served nowhere and accepts no deploys until the block is lifted, and nothing of it has been deleted — ask whoever administers this installation"
}

One answer is not a scafo failure:

A failure the node did not expect is one: it is answered as internal, with the real error written to the node's log and never exposed.

A deploy-overloaded answer additionally carries retry-after: 1.

#Code table

#Reading a problem document back

A client turns an answer back into the failure it describes rather than re-labelling it — flattening trust-mismatch and auth-invalid into one code would throw away the distinction the API is careful to keep.

Every member is checked rather than trusted, because what arrives may have come from a proxy, a load balancer or an error page:

#CLI rendering

Every command wraps its work in one reporter.

The unexpected-failure chain follows cause up to four levels deep, because fetch reports TypeError: fetch failed and puts the refused connection in its cause — a renderer stopping at the top would print nothing an operator could act on.

A failure answered by a node is re-rendered from that node's own problem document, so the code printed is the code the node chose.

#Ingress-side failures

#The Caddy module

The dynamic-upstreams module cannot choose a status code — Caddy's answer to no upstreams is 503 — so it records why in scafo.route and leaves the answer to a handle_errors route.

scafo.host carries the normalized host the lookup was keyed by, scafo.matched the routing entry that answered and scafo.fleet the fleet that answered. Answering denied the same way as unknown is deliberate: a distinct status would confirm that the path exists.

For storage, a 404 is translated into an error wrapping io/fs.ErrNotExist, which is what CertMagic checks with errors.Is to tell a missing key from a broken backend.

#Traefik

Traefik's http provider logs a failed fetch and keeps its previous configuration. A 503 urn:scafo:draining from a node that has not finished its first reconcile pass is therefore a pause in the provider rather than a withdrawal of every route — treat it as any other fetch failure, never as an empty document.

The renderer answers {} rather than empty maps when there is nothing to publish, because empty maps make Traefik retain stale provider configuration.