Skip to content

Error catalogue: every error apic prints, its exit code and the fix #65

Closed

Description

@dataGriff

Why

apic's errors are already good ("it is captured by request login; run apic run login first"). A single page that lists every one, with the exit code and what to do, is what the FAQ, the agent guide and the VS Code extension's quick fixes all want to link to, and it is the page search engines land people on.

What

  • Give every user-facing error a stable code (E101 missing variable, E201 unknown request, E301 transport, …) carried on the error type in internal/runner/errors.go and surfaced in --json as "error": {"code", "message", "hint"} (additive to the current shape; README contract note).
  • docs/errors.md generated by task docs:errors from a table in the code (code, exit status, message template, hint, longer explanation), so it cannot drift; CI staleness check like the other generated docs.
  • Each printed error ends with the short URL of its entry when stderr is a terminal (see https://datagriff.github.io/api-caller/errors/#e101), and apic validate diagnostics carry the same codes.
  • The FAQ links each answer to its code; docs/agents.md tells agents to read error.code.

Where

internal/runner/errors.go, internal/cli/root.go (error printing), internal/output, scripts/errors/, docs/errors.md, mkdocs.yml (Reference nav), docs/faq.md, docs/agents.md, docs/cli.md.

Tests

Every code in the table is produced by at least one test (a test that walks the table and checks a registry of "exercised" codes); --json error shape.

Activity

  1. dataGriff commented on Sep 24, 2026

    @dataGriff
    OwnerAuthor

    Done in #116 (commit da5ffc5).

    • Codes: every error has a stable code from runner.Catalogue. E1xx is the request, E2xx the command and project, E3xx the network.
    • --json: the error is written to stderr as {"error": {code, title, message, hint, exit, url}}. A run result carries the same object as error.
    • MCP: tool errors carry the same object as structured content.
    • Terminal: a dim line gives the code and its URL.
    • Docs: docs/errors.md is generated by task docs:errors, with a staleness test.
    • Tests: TestEveryCodeIsProduced runs a real command for every code in the catalogue.
    • VS Code extension: it reads the stderr object and offers "What is E101?".
    • Validate diagnostics: these keep their own documented namespace (bad-ref, unknown-selector, …), listed on the same page.

    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions