Skip to content
Agar0.5.0
API reference

errors

Import

Section titled “Import”
Import
import * as api from "@fungi.computer/agar/errors";

Exports

Section titled “Exports”
Kind Export Description
class AppError The SDK’s one typed failure. Carries a closed code naming the failure kind and an explicit retryable verdict, instead of leaving callers to guess either from the message or exception shape.
type alias MediaProviderDiagnostic Declaration-safe projection of the canonical Media diagnostic grammar.
type alias AppErrorCode One closed App error code from appErrorCodes.
type alias AppDeliveryPending One pending-delivery refusal shared by admission and the shell.
type alias AppErrorOptions Required construction options for an AppError.
type alias ErrorCopy Trusted presentation copy; overrides never change recovery or retry policy.
type alias ErrorDescription Recovery hints are for the caller’s UI, never an instruction to retry automatically.
constant mediaProviderDiagnosticWireSchema Documentable wire projection of the canonical diagnostic grammar. Maintained converters preserve its closed objects and numeric bounds; decoding still returns the declaration-safe public diagnostic type.
constant appErrorCodes The closed set of reasons an AppError can state; every SDK and host-reported failure is tagged with exactly one of these codes.
function decodeMediaProviderDiagnostic() Decode only safe provider facts, rejecting unmodeled private fields.
function decodeMediaProviderErrorCategory() Decode an ordinary Error name without retaining arbitrary upstream text.
function describeAppError() Describe an SDK-decoded failure without exposing exception or request data. The error owner retains retry truth. Grant and reconnect hints describe prerequisites, so they can accompany a non-retryable operation.

AppErrorclass

Section titled “AppError”

The SDK’s one typed failure. Carries a closed code naming the failure kind and an explicit retryable verdict, instead of leaving callers to guess either from the message or exception shape.

Extends

Section titled “Extends”
  • Error

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new AppError(message, options): AppError;
Parameters
Section titled “Parameters”
Parameter Type
message string
options AppErrorOptions
Returns
Section titled “Returns”

AppError

Overrides
Section titled “Overrides”
Signature
Error.constructor;

Properties

Section titled “Properties”

code

Section titled “code”
Signature
readonly code:
  | "CANCELLED"
  | "CAPABILITY_DENIED"
  | "CAPABILITY_REVOKED"
  | "COMMAND_NOT_DECLARED"
  | "CONFLICT"
  | "DELIVERY_PENDING"
  | "DISCONNECTED"
  | "FILE_TOO_LARGE"
  | "HOST_FAILURE"
  | "IDENTITY"
  | "INSUFFICIENT_CREDIT"
  | "INVALID_ARGUMENT"
  | "PROTOCOL"
  | "SAFETY_FILTER_REFUSED"
  | "SELECTION_CHANGED"
  | "TIMEOUT";

retryable

Section titled “retryable”
Signature
readonly retryable: boolean;

MediaProviderDiagnostictype alias

Section titled “MediaProviderDiagnostic”
Signature
type MediaProviderDiagnostic =
  | Readonly<{
      category:
        | "InferenceUpstreamError"
        | "AiInternalError"
        | "TypeError"
        | "AbortError"
        | "TimeoutError"
        | "Error";
      code: number | null;
    }>
  | Readonly<{
      category: "result_download";
      status: number;
    }>;

Declaration-safe projection of the canonical Media diagnostic grammar.

AppErrorCodetype alias

Section titled “AppErrorCode”
Signature
type AppErrorCode = (typeof appErrorCodes)[number];

One closed App error code from appErrorCodes.

AppDeliveryPendingtype alias

Section titled “AppDeliveryPending”
Signature
type AppDeliveryPending = Readonly<{
  code: Extract<AppErrorCode, "DELIVERY_PENDING">;
}>;

One pending-delivery refusal shared by admission and the shell.

AppErrorOptionstype alias

Section titled “AppErrorOptions”
Signature
type AppErrorOptions = object;

Required construction options for an AppError.

Properties

Section titled “Properties”

cause?

Section titled “cause?”
Signature
readonly optional cause?: unknown;

code

Section titled “code”
Signature
readonly code: AppErrorCode;

retryable

Section titled “retryable”
Signature
readonly retryable: boolean;

Every error states retry truth explicitly; absence is not a verdict.

ErrorCopytype alias

Section titled “ErrorCopy”
Signature
type ErrorCopy = Readonly<{
  title: string;
  message: string;
}>;

Trusted presentation copy; overrides never change recovery or retry policy.

ErrorDescriptiontype alias

Section titled “ErrorDescription”
Signature
type ErrorDescription = ErrorCopy &
  Readonly<{
    retryable: boolean;
    action?: "grant" | "retry" | "reconnect" | "billing";
  }>;

Recovery hints are for the caller’s UI, never an instruction to retry automatically.

mediaProviderDiagnosticWireSchemaconstant

Section titled “mediaProviderDiagnosticWireSchema”
Signature
const mediaProviderDiagnosticWireSchema: ZodPipe<
  ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>,
  ZodTransform<
    | Readonly<{
        category:
          | "InferenceUpstreamError"
          | "AiInternalError"
          | "TypeError"
          | "AbortError"
          | "TimeoutError"
          | "Error";
        code: number | null;
      }>
    | Readonly<{
        category: "result_download";
        status: number;
      }>,
    unknown
  >
>;

Documentable wire projection of the canonical diagnostic grammar. Maintained converters preserve its closed objects and numeric bounds; decoding still returns the declaration-safe public diagnostic type.

appErrorCodesconstant

Section titled “appErrorCodes”
Signature
const appErrorCodes: readonly [
  "CANCELLED",
  "CAPABILITY_DENIED",
  "CAPABILITY_REVOKED",
  "COMMAND_NOT_DECLARED",
  "CONFLICT",
  "DELIVERY_PENDING",
  "DISCONNECTED",
  "FILE_TOO_LARGE",
  "HOST_FAILURE",
  "IDENTITY",
  "INSUFFICIENT_CREDIT",
  "INVALID_ARGUMENT",
  "PROTOCOL",
  "SAFETY_FILTER_REFUSED",
  "SELECTION_CHANGED",
  "TIMEOUT",
];

The closed set of reasons an AppError can state; every SDK and host-reported failure is tagged with exactly one of these codes.

decodeMediaProviderDiagnostic()function

Section titled “decodeMediaProviderDiagnostic()”
Signature
function decodeMediaProviderDiagnostic(input): MediaProviderDiagnostic;

Decode only safe provider facts, rejecting unmodeled private fields.

Parameters

Section titled “Parameters”
Parameter Type
input unknown

Returns

Section titled “Returns”

MediaProviderDiagnostic

decodeMediaProviderErrorCategory()function

Section titled “decodeMediaProviderErrorCategory()”
Signature
function decodeMediaProviderErrorCategory(
  input,
):
  | "InferenceUpstreamError"
  | "AiInternalError"
  | "TypeError"
  | "AbortError"
  | "TimeoutError"
  | "Error";

Decode an ordinary Error name without retaining arbitrary upstream text.

Parameters

Section titled “Parameters”
Parameter Type
input string | undefined

Returns

Section titled “Returns”

| "InferenceUpstreamError" | "AiInternalError" | "TypeError" | "AbortError" | "TimeoutError" | "Error"

describeAppError()function

Section titled “describeAppError()”
Signature
function describeAppError(cause, overrides?): ErrorDescription;

Describe an SDK-decoded failure without exposing exception or request data. The error owner retains retry truth. Grant and reconnect hints describe prerequisites, so they can accompany a non-retryable operation.

Parameters

Section titled “Parameters”
Parameter Type
cause unknown
overrides? Partial<Record< | "CANCELLED" | "CAPABILITY_DENIED" | "CAPABILITY_REVOKED" | "COMMAND_NOT_DECLARED" | "CONFLICT" | "DELIVERY_PENDING" | "DISCONNECTED" | "FILE_TOO_LARGE" | "HOST_FAILURE" | "IDENTITY" | "INSUFFICIENT_CREDIT" | "INVALID_ARGUMENT" | "PROTOCOL" | "SAFETY_FILTER_REFUSED" | "SELECTION_CHANGED" | "TIMEOUT", Readonly<{ title: string; message: string; }>>>

Returns

Section titled “Returns”

ErrorDescription