apierr

Documentation

Overview

Package apierr provides structured error types for tier0 CLI API calls. When the backend returns a non-2xx HTTP status, the CLI wraps it in an APIError and attaches a human-readable hint so AI agents and users know exactly what to do next.

Index

• type APIError
  • func New(httpStatus int, rawBody string) *APIError
  • func NewBusiness(code int, rawBody string) *APIError
  • func (e *APIError) Category() errs.Category
  • func (e *APIError) Error() string
  • func (e *APIError) Format() string
  • func (e *APIError) ToEnvelope() errs.Envelope

Types

type APIError

type APIError struct {
	// HTTPStatus is the HTTP status code (401, 403, 404 …).
	HTTPStatus int
	// Code is the backend ResultVO code (may differ from HTTPStatus).
	Code int `json:"code,omitempty"`
	// Message is the human-readable error message from the backend.
	Message string
	// Hint is the suggested next action for the caller / AI agent.
	Hint string
	// HintCommand is a ready-to-run CLI command that fixes the problem, if applicable.
	HintCommand string
}

APIError is a structured error returned by the backend API.

func New

func New(httpStatus int, rawBody string) *APIError

New builds an APIError from an HTTP status code and the raw response body, automatically attaching an appropriate hint.

func NewBusiness

func NewBusiness(code int, rawBody string) *APIError

NewBusiness builds an APIError from a Tier0 business-envelope code. Business codes are not HTTP status codes and must never become retryable merely because their numeric value is greater than 500.

func (*APIError) Category

func (e *APIError) Category() errs.Category

Category returns the errs.Category corresponding to the HTTP status code. This is used by the central error dispatcher to select the exit code and the JSON "type" field.

func (*APIError) Error

func (e *APIError) Error() string

func (*APIError) Format

func (e *APIError) Format() string

Format returns the JSON representation of the error (unified envelope). Kept for backward compatibility; prefer ToEnvelope().Format().

func (*APIError) ToEnvelope

func (e *APIError) ToEnvelope() errs.Envelope

ToEnvelope converts an APIError into the unified errs.Envelope for JSON output.