Engine error and status codes

This page is the lookup for the HTTP outcomes the engine admin API returns: the status codes, the shape of each error body, what causes it, and what to do about it. It is for a developer integrating with the engine directly rather than through the console.

Hold this first: the content type is part of the contract, not an accident, and it decides an operator’s day at the 401. A plaintext body carrying unauthorised is a genuine authentication failure and the caller should sign in again. A JSON body carrying stepUpRequired at that same 401 status is a gated route asking a still-valid session for a fresh identity proof, and a client that reads it as a lapsed session signs out an operator who was never signed out. A failed capability check is a JSON 403. This page is the HTTP-channel view of the admin surface; for how a caller authenticates and the full role-by-capability matrix, see authentication and authorisation, and for the offline reader’s process exit codes (a separate contract) see the CLI exit codes.

The status channels at a glance

The channels below carry the admin API. A few statuses sit outside this table. The /support/diagnostics and /support/audit-feed pull routes answer 503 when the engine cannot read their grant, seal the diagnostics bundle or read the audit log. The SCIM endpoint answers 503 when SCIM is not enabled. Some admin routes answer 502 when the engine cannot read its own scheduler state. A request over TLS 1.1 or older gets a plaintext 426 before any route runs.

A request whose method and path match no route at all returns a plain not found with status 404 (engine/src/admin/router.ts). The CORS allowlist is exact: the engine reflects Access-Control-Allow-Origin only for the configured console origin, so a call from any other origin gets no CORS headers back rather than a wildcard (corsHeaders, engine/src/index.ts). The one exception is the unauthenticated GET /admin/health probe, which answers with a wildcard origin and no credentials.

The 401 channel: two bodies that mean opposite things

A 401 is the one status on this surface that does not identify its own meaning. Read the body before you act on it.

The plaintext unauthorised is the authentication failure. It carries no JSON envelope. The engine returns it from the auth boundary, logging a coarse failure line that never carries a token, an assertion, or an email (logAuthFailure, engine/src/admin/router-core.ts).

The JSON { "error": "step-up required", "stepUpRequired": true } at the same status is not an authentication failure at all (requireStepUp, engine/src/admin/router-core.ts). The caller is authenticated, their session is live, and a step-up gated route is asking for a fresh proof of presence before it acts. The two are covered separately below, because a client that handles them the same way has a bug that only shows up on the sensitive routes.

The anti-downgrade rule is the property to note here. Precedence is Access, then the session cookie, then the token. A present-but-invalid step is rejected outright rather than retried at a lower tier (authorise, engine/src/admin/auth.ts). If you see a 401 with what you believe is a valid token, check that you did not also send an invalid Access header or a stale cookie, because the higher method is consulted first and its failure stops the request.

The JSON 401: step-up required

Two properties of this row matter more than the row. The first is that a bare ADMIN_TOKEN caller never sees this 401, because the bare token is exempt from step-up. A Cloudflare Access caller sees it only when its Access sign-in is more than five minutes old, so the body then also carries reauth: "access" and the fix is a fresh Access sign-in, not the passkey ceremony. The second is that the gate fails closed: if the engine cannot reach the component that answers the freshness question, it returns this same body rather than admitting the request. A client cannot distinguish those two from the wire, which is why the fleet-wide version of the symptom is diagnosed by blast radius rather than by the response, on step-up re-authentication.

The 403 channel: three different rejections

A 403 is always JSON, and at the auth boundary it has three shapes that mean different things. Discriminate them by the error field, because no two of them share a remedy. Two further 403s carry a named dual-control payload and are documented under named JSON payloads rather than here.

The capability gate

When a caller authenticated but their role does not hold the capability a route requires, the engine returns the Forbidden body: { "error": "forbidden", "required": "<capability>", "have": "<role>" } (gate in engine/src/admin/router-core.ts, and the Forbidden interface in engine/src/admin/identity.ts). The required field is the capability the route gates on, and have is the caller’s resolved role, so a client can say “your operator role cannot run a key ceremony” rather than showing a mystery failure.

For a custom-role caller the have field reports the viewer floor while the real authority is the caller’s resolved capability set, so read the failure as “this caller does not hold required”, not as a literal statement about the floor role (gate, engine/src/admin/router-core.ts).

The cross origin write rejection (CSRF)

A separate 403 guards cookie-borne sessions against a forged cross origin write. A mutating request (anything that is not GET or OPTIONS) authenticated by an ambient session cookie must also carry an Origin that exactly matches the configured console origin; if it does not, the engine returns { "error": "csrf origin check failed" } before reading the body or touching state (engine/src/admin/router.ts).

The double-submit token rejection

The session-termination routes and the sign-in-factor revoke route carry a second, independent CSRF check on top of the Origin check above: a double-submit token. A cookie-borne request to one of those routes must present the x-downpipes-csrf header carrying the same value as its __Host-downpipes_csrf cookie; one that does not is refused with { "error": "csrf token check failed" } before any rate-limit or storage work (csrfBlock, engine/src/admin/router-account-session.ts). It is a different string from the origin rejection deliberately, because it has a different cause and a different fix.

The way to tell the three apart is the error value, and a client must match all three rather than the first two. A forbidden body means change the caller’s role. A csrf origin check failed body means fix where the request is coming from. A csrf token check failed body means the request is coming from the right place but is not carrying the token that proves it.

Only a cookie-borne session can hit a CSRF 403. A passkey, native OIDC or native SAML session can hit both. A token session minted from the ADMIN_TOKEN bearer can hit the origin check only. An Access caller or a bare-bearer caller never hits either, because their explicit header is not a cross-site-ridable ambient credential.

Named JSON payloads worth knowing

Beyond the bare channels, a few routes return a named JSON body that an integrator should match on. Each entry below gives the body shape.

restore not approved on an apply

A restore apply (POST /admin/restore with confirm: true) needs the restore.apply capability. When an owner turns on restore dual control, the apply also needs a second identity’s approval. That approval binds to the same plan hash, and the maker cannot be the checker. The policy is off by default. If the capability passes but no usable approval exists, the engine returns a 403 with { "error": "restore not approved", "planHash": "<hash>" } and records a denied apply (engine/src/admin/router-restore.ts).

The planHash in the body is the engine’s server-recomputed binding for the plan, so it is the value to pass to the approve route. This is a capability gate the console routes to “awaiting approval”, not an error to retry blindly. A changed plan produces a different hash and voids any prior approval, which is why dual control is covered in full on dual control.

A request raised against a plan that has aged out

POST /admin/restore/request binds the approval to a dry run, and the approval’s twenty-four hours are counted from that dry run rather than from the request. A request raised more than twenty-four hours and thirty minutes after the plan it names is refused with a 400 carrying { "error": "the plan this request is raised against is older than this engine will vouch for; run the dry run again and request from the plan it returns" } (engine/src/sched/scheduler-do-restore-approval.ts).

Match this separately from the 403 refusals above: it is not an authority problem and no amount of approving will clear it. The remedy is a fresh preview, which is also the disclosure the requester needs. The window and where it starts are covered on dual control.

prune not approved on a retention prune

Retention pruning has the same request, approve, apply shape as a restore, and a dual-control gate on every real apply. An apply with no usable approval bound to that exact plan is a 403 with { "error": "prune not approved", "downpipeId", "planHash", "mode": "not-approved", "retainedRuns", "supersededRuns" } (engine/src/admin/router-retention-prune.ts).

The two run counts in the body are the reason to parse this rather than treat it as a bare refusal. They tell the caller what the refused plan would have done, so an approver can be shown the consequence before they approve rather than after.

unknown report kind, unknown framework and unknown channel

A report request for a kind the engine does not recognise is a 404 with { "error": "unknown report kind" }. An evidence pack asked for a ?framework= the engine does not map is a 404 with { "error": "unknown framework" } (both handleReport, engine/src/admin/router-posture.ts). The notification test-send route returns { "error": "unknown channel" } with the same 404 status for a channelId the engine does not hold (engine/src/admin/router-ops.ts).

report could not be rendered

One 500 on this surface is route-specific rather than the generic dispatch fault below. This 500 is worth knowing because of what it does not mean. A report request with ?format=pdf whose data was gathered and signed successfully but whose PDF render threw returns { "error": "report could not be rendered" } (handleReport, engine/src/admin/router-posture.ts).

Do not read this as an unavailable report. The distinction is the whole value of the separate string: the generic internal error says the engine could not answer, and this one says it answered and could not draw the answer.

The 202 owner-action-queued response

Several owner operations are dual-control gated. When the gate is on and no armed approval exists yet, the route records a pending approval and returns 202 with { "ownerActionQueued": true, "id": "<id>", "status": "pending" } (ownerActionQueuedResponse, engine/src/admin/router-core.ts). This is the single most important non-failure to handle correctly.

Do not retry a 202 as though it errored. The action has been recorded under id and is waiting for a second owner; the privileged step (for example minting a one-shot token) runs only on the approved re-submit, never on this first call (ownerActionGate, engine/src/admin/router-core.ts).

Rate limiting and the 429

Every rate-limit 429 the engine returns carries the same body: an RFC 9457 problem+json document (application/problem+json) with type, title, status and an error field that a client matches on (error === "rate limited", or "rate limit unavailable" from a fail-closed limiter), plus a Retry-After header in whole seconds, rounded up so a client never retries a hair early into a still-saturated window, and the advisory IETF RateLimit and RateLimit-Policy headers beside it. One builder produces all of them (rateLimitedResponse, engine/src/admin/router-core.ts), so the shape does not vary by which limiter refused. A dual-control approve that arrives within five seconds of its request gets a different 429. Its application/json body is { error, refusal: "too-soon", retryAfterSeconds }, with a Retry-After header (engine/src/sched/scheduler-do.ts).

There is more than one limiter. They differ in what they are keyed on and how they behave when their own backing store is unavailable.

Two properties matter for an integrator. First, the per-caller limiter is keyed on the verified caller (the caller’s stable subject, or one shared bucket for the bare token) rather than the source IP, so a shared NAT does not lock out legitimate callers; the two per-IP limiters above are keyed the other way, in their own separate namespaces, because they guard credential-guessing surfaces where the caller is not yet established. Second, the per-caller limiter fails open: if its backing store is unavailable the request is admitted rather than denied, because this is an authenticated admin and recovery surface where availability beats strict limiting (rateLimited, engine/src/admin/router-core.ts). The two per-IP limiters fail closed for the opposite reason: a brute-force gate that opens when its counter breaks is not a gate. The windows and caps are constants in the scheduler Durable Object (RATE_LIMIT_WINDOW_MS, RATE_LIMIT_MAX_PER_WINDOW and the per-IP caps beside them, engine/src/sched/scheduler-do-limits.ts); read them there rather than hard-coding a number, since they are an operational tuning, not a wire contract.

A 429 is never a session loss. The break-glass throttle in particular refuses before any credential is compared, so it establishes nothing about the token presented. A client that treats a rate limit as an expired session and signs the operator out is reading it wrongly, which is why the engine answers 429 for it rather than the 401 every genuine authentication failure returns.

The 500 channel: an unhandled fault

A 500 is the engine’s own last-resort handler, not a route-specific refusal. Both the admin dispatch and the outer Worker entry run under a single top-level catch, so a route handler that throws unexpectedly lands here rather than escaping the response unlogged (engine/src/index.ts). The body is the same RFC 9457 problem+json shape the 429s use, with error: "internal error" and a requestId that also rides on the response as the x-downpipe-request-id header, so a client and the engine’s own log line can be matched by the one value.

What this reference does not cover

Two things are deliberately out of scope here. The first is the reader’s process exit codes: the offline downpipe tool returns numeric exit statuses (0 verified, 2 unverified, and so on) that are a different contract from these HTTP codes, documented on the CLI exit codes. The second is the DELETE, PUT and PATCH verbs: the admin API mutates exclusively through POST and reads through GET, so those verbs are not part of the surface and are not documented as error rows.

Where this fits

These are the wire-level outcomes; the pages below give the surrounding model.

Last updated 25 September 2026.