piagent-pretty-api-error

Pi extension that renders provider/API errors (e.g. OpenRouter 429 JSON payloads) in a readable form instead of raw JSON.

Table of contents

• Behavior
• Features
• Installation
• Commands
• Dependencies
• Changelog

Behavior

Error line (short):

Error: ✖  API error · HTTP 429 · rate limit · Details: ctrl+o

Below it, a red panel with inner padding, column-aligned labels and a hanging indent for wrapped values:

                                          ← inner padding (top)
✖  API error · HTTP 429 · rate limit      ← title (bold)

Provider:  openrouter · Upstream: Fireworks
Model:     deepseek/deepseek-v4.1-flash
Reason:    Provider returned error
Upstream:  deepseek/… is temporarily rate-limited upstream. Please retry shortly,
           or add your own key to accumulate your rate limits: …
Code:      invalid_request_error
Hint:      Retry shortly, add your own provider key …

ctrl+o · show raw data                    ← dimmed
                                          ← inner padding (bottom)

ctrl+o (app.tools.expand) expands the raw data - as a directly attached, darker panel with the same width/alignment (visibly part of the error). If the raw data contains JSON, it is shown indented (label then Raw data (JSON):, the leading status stays as a headline):

…
ctrl+o · hide raw data

Raw data (JSON):
429:
{
  "message": "Provider returned error",
  "code": 429,
  "metadata": {
    "raw": "deepseek/… is temporarily rate-limited upstream. Please retry shortly.",
    "provider_name": "Fireworks",
    "provider_error_code": "invalid_request_error"
  }
}

• Only when the text is parseable; otherwise the raw data stays unchanged.
• Long values/URLs wrap with a hanging indent below the value (not flush-left).
• Truncated above 8000 chars (… truncated (N chars)) so the block does not flood.

Features

• The detail panel is a CustomEntry → not part of the LLM context, but it is persisted with the session and re-rendered on resume/reload.
• The entry is attached at agent_settled only, i.e. only for final errors (no raw-data blocks for failed attempts that still retry successfully).
• Retry semantics stay untouched: Pi classifies errors via isRetryableAssistantError(message.errorMessage). The short line is only applied when the classification stays identical - otherwise the error stays raw.
• The red panel is its own component: it fills the terminal width and wraps long lines itself (no clipped/torn layout on narrow terminals). Structure: PiTUI Box (padding + background) around an ErrorBlock that aligns labels in a column and indents continuation lines to the value column.
• Colors are chosen via getCapabilities().trueColor:
  • 24-bit (Windows Terminal, kitty, iTerm2, Ghostty, …): message rgb(96,22,22), raw data rgb(54,14,14)
  • 256-color fallback: both color 52 (darkest red in the palette), raw data additionally set apart via text color (181 instead of 224)

Installation

Local (development):

pi -e ./extensions/api-error-format.ts

As a pi package (GitHub or npm):

pi install git:[email protected]:FloezWerk/piagent-pretty-api-error.git
# or
pi install npm:@floez-werk/piagent-pretty-api-error

The npm package is listed in the pi package catalog automatically (keyword pi-package).

Alternatively copy the file to ~/.pi/agent/extensions/ (auto-discovery).

Commands

| Command | Effect | | --- | --- | | /apierrors preview | Appends a sample error block (testable with ctrl+o) | | /apierrors on | Red background on | | /apierrors off | Red background off |

After changes in a running session: /reload.

Dependencies

@earendil-works/pi-ai, @earendil-works/pi-coding-agent and @earendil-works/pi-tui are bundled by pi and are therefore only declared as peerDependencies.

Changelog

Notable changes per version are documented in CHANGELOG.md. Every tagged release (vX.Y.Z) is published to npm and appears as a GitHub release with the package tarball.

0.1.3 - 2026-09-19

Changed

• Release tooling and CI/CD now come from pi-extension-release-tool: the README release-notes block and the GitHub release notes are generated by the published pi-release CLI, and CI/release run through its shared reusable workflows (pinned @v0.1). The local scripts/ copies are gone.

Full history and all versions: CHANGELOG.md