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:git@github.com: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.4 - 2026-10-13

Changed

• Published to npm via trusted publishing instead of a stored npm token.

Full history and all versions: CHANGELOG.md