Errors

Error response shape

HTTP error bodies usually look like:

{
  "error": "payment_required",
  "message": "Payment required"
}

The SDK throws typed errors instead of returning raw bodies for failed calls.

import { SDKError, APIError, PaymentRequiredSDKError } from "galliun";

try {
  await client.inference.chat({ model: "...", messages });
} catch (err) {
  if (err instanceof PaymentRequiredSDKError) {
    // Wallet payment failed or was rejected
  } else if (err instanceof APIError) {
    console.error(err.statusCode, err.message);
  } else if (err instanceof SDKError) {
    console.error(err.message);
  }
}

Common cases

Authentication errors

Meaning: Missing or invalid bearer token, or auth wallet does not match payment wallet.

Cause: Calling conversations / storeConversation without ensureAuthenticated(), or using different wallets for auth and payment.

Do: Call client.inference.auth.ensureAuthenticated() with an inference wallet that supports signMessage.

Insufficient / rejected payment

Meaning: payment_required or payment verification failed.

Cause: Not enough USDC, wrong chain, expired requirement, or transaction not confirmed.

Do: Fund the wallet, confirm chain matches the adapter, and retry. Ensure Solana txs reach confirmation before retry (the SDK waits for confirmation).

Invalid parameters

Meaning: Bad request body, path, or model fields rejected by the API.

Cause: Missing required fields, invalid JSON, or malformed path params.

Do: Match directory examples and OpenAI-style chat schemas. Check APIError message / responseBody.

Unsupported model or endpoint

Meaning: Model ID unknown/disabled, or marketplace path not found.

Cause: Typos, disabled models, or unpublished endpoints.

Do: Use models.list() and directory.getApi() for live IDs and paths.

Upstream provider errors

Meaning: The underlying AI provider or marketplace origin failed after payment was accepted.

Cause: Provider outage or origin error.

Do: Retry later; check the error message. Contact the API publisher for marketplace origins.

Missing wallet or chain

Meaning: SDKError about wallet/chain configuration.

Cause: Calling a paid route without the matching adapter or chain option.

Do: Pass wallet for marketplace and inferenceWallet for inference. See Connect a wallet.