Skip to content

docs: add error-codes reference page and v0.14.0 changelog#9

Merged
indykish merged 13 commits intomainfrom
feat/error-codes-and-changelog
Apr 12, 2026
Merged

docs: add error-codes reference page and v0.14.0 changelog#9
indykish merged 13 commits intomainfrom
feat/error-codes-and-changelog

Conversation

@indykish
Copy link
Copy Markdown
Contributor

@indykish indykish commented Apr 12, 2026

Summary

This PR adds documentation for API error codes and updates the changelog with the v0.14.0 memory feature release.

Changes

  • New:

    • — comprehensive reference for all error codes (UUID, Auth, API, Workspace, Billing, Entitlement, Spec, Run, Agent, Proposal, Webhook, Tool, Zombie, Approval gate, Credentials, Relay)
  • Updated:

    • — add error-codes to API Reference navigation
    • — add v0.14.0 release notes for Persistent Zombie Memory (M14_001)

Checklist

  • Error codes follow RFC 7807 format with , , , ,
  • All error categories documented with HTTP status mappings
  • Changelog entry follows Mintlify Update format

Greptile Summary

This PR adds a new api-reference/error-codes.mdx reference page covering all RFC 7807 error codes, adds changelog entries for v0.8.0–v0.14.0, removes deprecated endpoint pages (agent-stream.mdx, list-specs.mdx), and cleans up docs.json navigation.

  • The docs_uri example in the response format section uses per-code URL fragments (e.g., #UZ-ZMB-009), but the page has no HTML anchors on table rows — browsers will silently ignore the fragment, breaking the "link to the specific code" promise documented in the field description.

Confidence Score: 4/5

Safe to merge after fixing the docs_uri anchor gap, which misrepresents a documented API contract to callers.

One new P1 found: the docs_uri deep-link mechanism is documented as linking to the specific code but won't work without per-row HTML anchors in the MDX. Prior review threads also flagged several unresolved issues (retired UZ-ENTL-002, missing v0.13.0 error codes, internal-detail violations). Until the anchor issue is resolved, the error codes page doesn't fulfill its stated RFC 7807 purpose.

api-reference/error-codes.mdx — missing per-row HTML anchors and incorrect HTTP status on UZ-RELAY-001

Important Files Changed

Filename Overview
api-reference/error-codes.mdx New error-codes reference page; docs_uri example uses per-code fragment anchors (#UZ-ZMB-009) that don't exist in the MDX, breaking the deep-link promise; UZ-RELAY-001 uses HTTP 400 for a dependency configuration issue.
changelog.mdx Adds v0.8.0–v0.14.0 changelog entries; internal implementation details (NullClaw tool names, RPC payload fields, zombie_memory.zig source file) and an internal annotation (RULE CTM) appear in user-facing content, violating AGENTS.md content boundaries — flagged in prior review threads.
docs.json Navigation updated cleanly: deprecated Specs, Agents, Harness, Agent Relay, and scoring groups removed; error-codes page added to API Reference overview. No issues found.
api-reference/endpoint/agent-stream.mdx File deleted — corresponds to the /v1/agent/stream endpoint removed when the harness/relay layer was retired in v0.10.1.
api-reference/endpoint/list-specs.mdx File deleted — corresponds to GET /v1/specs which returned HTTP 410 Gone after the v1 pipeline was removed in v0.8.0.

Sequence Diagram

sequenceDiagram
    participant Client
    participant zombied
    participant Docs as docs.usezombie.com

    Client->>zombied: API Request
    zombied-->>Client: 4xx/5xx application/problem+json
    Note over Client: Reads error_code, follows docs_uri
    Client->>Docs: GET /api-reference/error-codes#UZ-ZMB-009
    Note over Docs: Fragment #UZ-ZMB-009 has no matching anchor in MDX table rows
    Docs-->>Client: Page renders at top (not at specific error code)
Loading
Prompt To Fix All With AI
This is a comment left during a code review.
Path: api-reference/error-codes.mdx
Line: 12

Comment:
**`docs_uri` fragment anchors missing from page**

The example response advertises `"docs_uri": "https://docs.usezombie.com/api-reference/error-codes#UZ-ZMB-009"`, and the field description promises "Stable link to this page for the **specific code**." However, the MDX tables have no per-row HTML anchors — Mintlify only generates anchors for headings (`#zombie`, `#run`, etc.), not for table rows. A browser following `#UZ-ZMB-009` will silently ignore the unknown fragment and render the page top, so callers implementing RFC 7807 error handling will land on the wrong location every time.

To fix, add an anchor before each table row, for example:

```mdx
## Zombie

| Code | HTTP | Title | Common Causes |
|---|---|---|---|
| <a id="UZ-ZMB-009"></a>`UZ-ZMB-009` | 404 | Zombie not found | No zombie with this ID in the workspace |
```

Or, if Mintlify supports it, use a heading per code and nest rows under it. Either way, the `docs_uri` value embedded in `zombied`'s responses won't deep-link correctly until the page has matching anchors.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: api-reference/error-codes.mdx
Line: 212

Comment:
**`UZ-RELAY-001` HTTP status semantically incorrect**

HTTP `400 Bad Request` signals that the client sent a malformed or invalid request — callers treat it as "don't retry, fix your payload." But `UZ-RELAY-001` fires when the *workspace* has no LLM credentials configured, which is a server-side dependency failure, not a client error. A caller who receives 400 here has no obvious fix path.

`503 Service Unavailable` (workspace can't serve the request right now) or `424 Failed Dependency` (LLM provider dependency is absent) would give callers the correct retry/escalation signal.

```suggestion
| `UZ-RELAY-001` | 503 | No LLM provider configured | Workspace has no LLM credentials configured |
```

How can I resolve this? If you propose a fix, please make it concise.

Reviews (3): Last reviewed commit: "docs: fix error-codes accuracy issues fr..." | Re-trigger Greptile

Context used:

  • Context used - AGENTS.md (source)

indykish and others added 9 commits April 11, 2026 13:15
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ug fixes sections

The v0.5.0 entry was missing content from docs/release/0.5.0.md:
- Credential injection (vault-resolved, no creds in config files)
- Session checkpoint (crash-recovery via Postgres upsert)
- 6 post-review bug fixes (memory, YAML parser, migration runner, UTF-8, UUID, test runner)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Remove 4 implementation-internal fixes (memory, migration runner, UUID reads,
test infra) — not user-visible. Keep only YAML parser and UTF-8 truncation
fixes which affect observable CLI behavior.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add comprehensive error-codes.mdx with all UZ-* error codes, HTTP status mappings,
  and common causes for each category
- Add error-codes page to docs.json navigation under API Reference > Overview
- Add v0.14.0 changelog entry for Persistent Zombie Memory (M14_001) feature
- Remove GET /v1/specs from docs.json navigation (endpoint removed from API)
- Delete api-reference/endpoint/list-specs.mdx (endpoint no longer exists)

The /v1/specs endpoint was removed in a previous release. This cleans up
the documentation to match the current OpenAPI spec.
- Remove entire 'Agents' group from docs.json (8 endpoints removed from API)
- Remove entire 'Harness' group from docs.json (4 endpoints removed from API)

These endpoints were removed in v0.10.1 (M17_001). Cleaning up docs to match
current OpenAPI spec.
- Remove 'Agent Relay' group from docs.json (spec/template and spec/preview
  endpoints removed from API)
- Remove POST /v1/workspaces/{workspace_id}/scoring/config from Billing group
  (endpoint removed from API)
- Delete api-reference/endpoint/agent-stream.mdx (documents removed endpoint)

Cleaning up more stale references to match current OpenAPI spec.
- Fix UZ-AUTH-002: remove 'or expired' to avoid overlap with UZ-AUTH-003
- Remove UZ-ENTL-002: retired error code (harness-only, removed in v0.10.1)
- Remove UZ-AGENT-002: dead error code (endpoint removed in v0.10.1)

Addresses Greptile review feedback on PR #9.
@indykish indykish merged commit ce62dab into main Apr 12, 2026
4 checks passed
@indykish indykish deleted the feat/error-codes-and-changelog branch April 12, 2026 18:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant