Errors

The typed errors the SDK raises — PaymentRequiredError, FleeexApiError, and OpenAI errors.

The SDK raises three kinds of error.

PaymentRequiredError

Thrown when the proxy or getBalance() answers 402 — the (app, user) has no funded, authorized wallet. Carries the signed top-up link.

import { PaymentRequiredError } from "@fleeex/sdk";
 
try {
  await client.chat.completions.create({ model, messages });
} catch (err) {
  if (err instanceof PaymentRequiredError) {
    redirect(err.topupUrl);
  }
}

Property	Type	Notes
`status`	`402`	Always `402`.
`topupUrl`	`string \| undefined`	Signed, short-lived link to send the end user through Checkout.
`code`	`string \| undefined`	Machine-readable error code from the envelope.
`correlationId`	`string \| undefined`	Trace id for support/debugging.
`message`	`string`	Generic by design — never reveals whether a wallet exists.

The onPaymentRequired hook (see options) fires for the same condition before the error is thrown.

Any other non-2xx from a Fleeex billing helper (getConnection(), getUsageSummary(), or a non-402 from getBalance()) — for example a 400 when a redirectUri isn't on the app's allow-list.

Property	Type	Notes
`status`	`number`	HTTP status.
`code`	`string \| undefined`	Error code from the envelope.
`correlationId`	`string \| undefined`	Trace id.

OpenAI errors

For the proxy path, any error other than 402 is raised by the OpenAI SDK as OpenAI.APIError (and its subclasses) — e.g. a 400 for an unsupported model. Handle these exactly as you would with the OpenAI SDK.

import OpenAI from "openai";
import { PaymentRequiredError } from "@fleeex/sdk";
 
try {
  await client.chat.completions.create({ model, messages });
} catch (err) {
  if (err instanceof PaymentRequiredError) redirect(err.topupUrl);
  else if (err instanceof OpenAI.APIError) console.error(err.status, err.message);
  else throw err;
}

The error envelope

Fleeex's backend emits a consistent body, exposed as the FleeexErrorBody type. Only a 402 carries topupUrl.

interface FleeexErrorBody {
  error?: { code?: string; message?: string; correlationId?: string };
  topupUrl?: string;
}