Errors

class InkletError extends Error {
  readonly code: string;
  readonly status: number | undefined;
  readonly requestId: string | undefined;
  readonly details: Readonly<Record<string, unknown>> | undefined;
  readonly idempotencyKey: string | undefined;

  toJSON(): Record<string, unknown>;
}

catch (error) {
  if (error instanceof InkletError) {
    logger.error({ err: error.toJSON() }, "inklet push failed");
  }
}

Error
└── InkletError
    ├── ConfigurationError          invalid_configuration
    ├── BrowserEnvironmentError     browser_environment
    ├── AuthenticationError
    │   ├── AuthenticationFailedError   authentication_failed
    │   ├── InvalidSecretKeyError       invalid_secret_key
    │   └── RevokedSecretKeyError       revoked_secret_key
    ├── PermissionDeniedError       permission_denied
    │   └── SubscriptionRequiredError   subscription_required
    ├── NotFoundError               not_found
    ├── ConflictError               conflict
    ├── PayloadTooLargeError        payload_too_large
    ├── RateLimitError              rate_limited
    ├── AssetUploadError            asset_upload_failed
    ├── AnalysisFailedError         analysis_failed
    ├── NoChangeError               analysis_no_change
    ├── MultiplePresentationsError  analysis_multiple_presentations
    ├── OperationTimeoutError       operation_timed_out
    ├── OperationAbortedError       operation_aborted
    ├── ApiError                    api_error
    ├── InvalidResponseError        invalid_response
    └── NetworkError                network_error
        └── RequestTimeoutError     request_timed_out

{
  "error": {
    "code": "invalid_request",
    "message": "…",
    "requestId": "req_…",
    "details": {}
  }
}

try {
  await inklet.analyze({ contentIds: [content.id] });
} catch (error) {
  if (error instanceof ApiError && error.code === "no_compatible_display") {
    // Bind a display, or pass an { output } target instead.
  }
}

if (error instanceof ConflictError) {
  if (error.code === "idempotency_conflict") {
    // Same key, different body. Pick a new key or send the original body.
  }
  if (error.code === "invalid_state") {
    // The first call with this key has not answered yet. Wait and re-read.
  }
}

import { ApiError, PermissionDeniedError, RateLimitError } from "@inklethq/sdk";

try {
  await inklet.push.auto({ assets });
} catch (error) {
  if (error instanceof PermissionDeniedError && error.code === "plan_upgrade_required") {
    // Upgrade in the inklet portal, then retry with the same PAT.
  }
  if (error instanceof ApiError && error.code === "payment_required") {
    // The card needs attention in the billing portal.
  }
  if (error instanceof RateLimitError && error.code === "quota_exceeded") {
    // error.details: { quota, limit, used, resetAt, currentTier }
  }
}

class AssetUploadError extends InkletError {
  readonly contentId: string | undefined;
  readonly failedAssetIndexes: readonly number[];
}

import { AssetUploadError } from "@inklethq/sdk";

try {
  await inklet.contents.upload({ assets });
} catch (error) {
  if (error instanceof AssetUploadError) {
    for (const index of error.failedAssetIndexes) {
      console.error("failed to upload:", assets[index]);
    }
  }
}

import {
  AuthenticationError,
  ConfigurationError,
  InkletError,
  NetworkError,
  PermissionDeniedError,
  RateLimitError,
} from "@inklethq/sdk";

async function push() {
  try {
    return await inklet.push.auto({ assets });
  } catch (error) {
    if (error instanceof ConfigurationError) {
      throw error; // our bug — fail loudly, do not retry
    }

    if (error instanceof AuthenticationError) {
      await alertOperator("inklet token needs rotating");
      throw error;
    }

    if (error instanceof PermissionDeniedError) {
      await alertOperator(`inklet refused: ${error.code}`);
      throw error; // not transient; the plan has to change first
    }

    if (error instanceof RateLimitError && error.code === "quota_exceeded") {
      throw error; // only time or an upgrade clears this — see details.resetAt
    }

    if (error instanceof RateLimitError || error instanceof NetworkError) {
      // Transient. Reuse the key so the retry cannot create a second push.
      return scheduleRetry({ idempotencyKey: error.idempotencyKey });
    }

    if (error instanceof InkletError) {
      logger.error({ err: error.toJSON() });
    }

    throw error;
  }
}