docs(error-codes): reconcile reference with the emittable registry (M92)

[indykish]

What

Reconciles the public error-codes reference with agentsfleetd's error registry — it had drifted to 45 undocumented real codes and 32 documented codes with no producer.

Why

Operators use this page to look up error_code values from application/problem+json responses. The drift meant (a) the entire runner control-plane + runner-engine contract, CLI login, API keys, and LLM-provider codes were undocumented, and (b) operators could chase codes (Billing / Workspace / Scoring / …) the API can never emit.

Changes

The page now mirrors exactly the 95 emittable registry entries (verified: registry e() entries == documented codes, zero drift).

Added (45) — runner control plane UZ-RUN-*, runner-engine UZ-EXEC-004..011, command-line interface (CLI) login UZ-AUTH-011..021, API keys UZ-APIKEY-*, large-language-model (LLM) provider UZ-PROVIDER-*, API load-shedding UZ-API-*, plus UZ-AGENT-001, UZ-AGT-012, UZ-APPROVAL-006, UZ-STARTUP-006.

Removed (34) — never-shipped sections (Billing, Workspace, Scoring, Entitlement, CI Gate, Credentials, Relay, Slack) and retired codes; each verified against the codebase (no producer, or an explicit retirement commit):

• UZ-MEM-001 → cross-workspace memory is now UZ-MEM-002 / 404 (retired this milestone — agentsfleet #417).
• UZ-AUTH-007/008, UZ-SLACK-001/002/003 → superseded surfaces, deliberately removed.
• UZ-WH-003, UZ-AGT-007 → retired (registry markers).
• UZ-BILLING-*, UZ-WORKSPACE-*, UZ-ENTL-*, UZ-GATE-*, UZ-GRANT-002/003, UZ-CRED-*, UZ-RELAY-001, UZ-SCORING-001, UZ-AGT-001/002/005, UZ-TOOL-004, UZ-STARTUP-007 → never raised (m90-003 / orphan-code sweeps).

Fixed — Pipeline v1 removal documented as 404 (the implementation returns 404, not the previously-documented 410); folded into a "Removed surfaces" note.

Related

Pairs with agentsfleet #417 (M92 error-registry cleanup + approval-gate hardening). The dotfiles error-codes gate was also fixed to stop missing digit-suffixed category codenames (UZ-UUIDV7-*).

🤖 Generated with Claude Code

Greptile Summary

This PR reconciles the public error-codes reference with the agentsfleetd error registry, eliminating 45 previously undocumented codes and removing 34 codes that had no producer — bringing the page to an exact mirror of the 95 emittable registry entries. The changelog is updated with a breaking-change entry for UZ-APPROVAL-005 gate-condition validation.

• Added sections: Runner control plane (UZ-RUN-*), runner engine (UZ-EXEC-004–011), CLI login (UZ-AUTH-011–021), API keys (UZ-APIKEY-*), LLM provider (UZ-PROVIDER-*), and API load-shedding (UZ-API-*).
• Removed sections: Billing, Workspace, Scoring, Entitlement, Gate, Credentials, Relay, and Slack — all verified as never-emitted or retired, with cross-references updated in a "Removed surfaces" prose note.
• Fixed: Pipeline v1 removal now correctly documented as returning 404 (not 410); UZ-MEM-001 cross-workspace scope retired to UZ-MEM-002/404.

Confidence Score: 4/5

Safe to merge after clarifying or correcting the UZ-RUN-013 entry, which tells runner implementors two contradictory things about whether a renewal succeeded.

The UZ-RUN-013 row documents HTTP 400 while simultaneously stating the lease is still renewed. A runner implementation that follows standard HTTP semantics will abort on a 400, potentially killing a run whose lease is actually still live. This documentation defect directly shapes how operators write runner clients and needs to be resolved before operators adopt the runner control-plane contract.

api-reference/error-codes.mdx — specifically the UZ-RUN-013 row in the Runner control plane table.

Important Files Changed

Filename	Overview
api-reference/error-codes.mdx	Comprehensive reconciliation of 95 error codes; one documentation contradiction in UZ-RUN-013 (HTTP 400 paired with "lease is still renewed") and two title-casing inconsistencies (UZ-APIKEY-007, UZ-PROVIDER-001).
changelog.mdx	Adds a well-structured M92 changelog entry covering the UZ-APPROVAL-005 breaking change and the error-codes reference update; no issues found.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[agentsfleet login] -->|device flow| B[CLI login UZ-AUTH-011..021]
    C[POST /v1/api-keys] -->|tenant key| D[API Keys UZ-APIKEY-*]
    C -->|agent key| E[UZ-AGENT-001]
    F[PUT /v1/tenants/me/provider] --> G[LLM Provider UZ-PROVIDER-*]
    H[Runner host] -->|/v1/runner/* lease protocol| I[Runner control plane UZ-RUN-*]
    I -->|claim / renew / report| J[Runner engine UZ-EXEC-*]
    K[Webhook ingest] --> L[Webhook UZ-WH-*]
    M[Agent trigger] --> N[Agent UZ-AGT-*]
    N --> O[Approval gate UZ-APPROVAL-*]
    N --> P[Vault UZ-VAULT-*]
    N --> Q[Memory UZ-MEM-*]
    R[agentsfleetd startup] --> S[Startup UZ-STARTUP-*]
    T[API instance] -->|load shedding| U[API limits UZ-API-*]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[agentsfleet login] -->|device flow| B[CLI login UZ-AUTH-011..021]
    C[POST /v1/api-keys] -->|tenant key| D[API Keys UZ-APIKEY-*]
    C -->|agent key| E[UZ-AGENT-001]
    F[PUT /v1/tenants/me/provider] --> G[LLM Provider UZ-PROVIDER-*]
    H[Runner host] -->|/v1/runner/* lease protocol| I[Runner control plane UZ-RUN-*]
    I -->|claim / renew / report| J[Runner engine UZ-EXEC-*]
    K[Webhook ingest] --> L[Webhook UZ-WH-*]
    M[Agent trigger] --> N[Agent UZ-AGT-*]
    N --> O[Approval gate UZ-APPROVAL-*]
    N --> P[Vault UZ-VAULT-*]
    N --> Q[Memory UZ-MEM-*]
    R[agentsfleetd startup] --> S[Startup UZ-STARTUP-*]
    T[API instance] -->|load shedding| U[API limits UZ-API-*]

Loading

_{Reviews (3): Last reviewed commit: "docs(error-codes): clarify UZ-AUTH-014 t..." | Re-trigger Greptile}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
megam	🟢 Ready	View Preview	Jun 17, 2026, 5:58 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.