@pdfvector/instance-client 0.0.50 → 0.0.51

package/.tsc/lib/errors.d.ts

@@ -1,4 +1,6 @@
 export type PDFVectorErrorCode = "BAD_REQUEST" | "UNAUTHORIZED" | "NOT_FOUND" | "TOO_MANY_REQUESTS" | "CONFLICT" | "NOT_IMPLEMENTED" | "UNPROCESSABLE_CONTENT" | "INTERNAL_SERVER_ERROR";
+export type PDFVectorErrorCategory = "authentication" | "validation" | "document_input" | "document_processing" | "rate_limit" | "not_found" | "conflict" | "unsupported" | "server";
+export type PDFVectorErrorOrigin = "user" | "system";
 export interface PDFVectorErrorOptions {
     code: PDFVectorErrorCode;
     status: number;
@@ -7,6 +9,25 @@ export interface PDFVectorErrorOptions {
     cause?: unknown;
 }
 type SubclassOptions = Omit<PDFVectorErrorOptions, "code" | "status">;
+export interface PDFVectorAgentError {
+    name: string;
+    code: PDFVectorErrorCode;
+    status: number;
+    category: PDFVectorErrorCategory;
+    origin: PDFVectorErrorOrigin;
+    userError: boolean;
+    title: string;
+    message: string;
+    suggestion: string;
+    retryable: boolean;
+    retryableWithHigherModel: boolean;
+    requestId?: number;
+    documentId?: string;
+    reasonCode?: string;
+    requestedModel?: string;
+    supportMessage: string;
+    data: Record<string, unknown>;
+}
 export declare class PDFVectorError extends Error {
     readonly code: PDFVectorErrorCode;
     readonly status: number;
@@ -14,7 +35,18 @@ export declare class PDFVectorError extends Error {
     readonly requestId?: number;
     readonly documentId?: string;
     readonly userError: boolean;
+    readonly category: PDFVectorErrorCategory;
+    readonly origin: PDFVectorErrorOrigin;
+    readonly title: string;
+    readonly suggestion: string;
+    readonly retryable: boolean;
+    readonly retryableWithHigherModel: boolean;
+    readonly requestedModel?: string;
+    readonly reasonCode?: string;
+    readonly supportMessage: string;
     constructor(options: PDFVectorErrorOptions);
+    toAgentError(): PDFVectorAgentError;
+    toJSON(): PDFVectorAgentError;
 }
 export declare class BadRequestError extends PDFVectorError {
     constructor(options: SubclassOptions);
@@ -28,6 +60,7 @@ export declare class NotFoundError extends PDFVectorError {
 export declare class TooManyRequestsError extends PDFVectorError {
     readonly limit?: number;
     readonly resetAt?: string;
+    readonly retryAfterSeconds?: number;
     constructor(options: SubclassOptions);
 }
 export declare class ConflictError extends PDFVectorError {
@@ -67,6 +100,10 @@ export declare class URLFetchError extends BadRequestError {
     readonly statusText?: string;
     constructor(options: SubclassOptions);
 }
+export declare class InvalidDocumentURLError extends BadRequestError {
+}
+export declare class InvalidBase64Error extends BadRequestError {
+}
 export declare class TierNotSupportedError extends BadRequestError {
     readonly documentType?: string;
     readonly model?: string;
@@ -88,6 +125,19 @@ export declare class ExtractionFailedError extends UnprocessableContentError {
     readonly rawText?: string;
     constructor(options: SubclassOptions);
 }
+export declare class AcademicPaperNotFoundError extends NotFoundError {
+    readonly input?: string;
+    readonly paperErrorCode?: string;
+    constructor(options: SubclassOptions);
+}
+export declare class NoPublicPDFError extends NotFoundError {
+    readonly input?: string;
+    readonly paperTitle?: string;
+    readonly doi?: string;
+    readonly providerURL?: string;
+    constructor(options: SubclassOptions);
+}
 export declare function fromORPCError(error: unknown): PDFVectorError | undefined;
 export declare function isPDFVectorError(error: unknown): error is PDFVectorError;
+export declare function isPDFVectorUserError(error: unknown): error is PDFVectorError;
 export {};

package/.tsc/lib/errors.js

@@ -14,6 +14,191 @@ function readStringArray(data, key) {
     const strings = value.filter((v) => typeof v === "string");
     return strings.length === value.length ? strings : undefined;
 }
+function readBoolean(data, key) {
+    const value = data?.[key];
+    return typeof value === "boolean" ? value : undefined;
+}
+function readNumberFromMatch(message, pattern) {
+    const match = message.match(pattern);
+    if (!match?.[1])
+        return undefined;
+    const number = Number.parseFloat(match[1]);
+    return Number.isFinite(number) ? number : undefined;
+}
+function readStringFromMatch(message, pattern) {
+    const match = message.match(pattern);
+    const value = match?.[1]?.trim();
+    return value ? value : undefined;
+}
+function readListFromMatch(message, pattern) {
+    const value = readStringFromMatch(message, pattern);
+    if (!value)
+        return undefined;
+    const items = value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return items.length > 0 ? items : undefined;
+}
+function hasHigherModelHint(message, data) {
+    const lower = message.toLowerCase();
+    return (readBoolean(data, "retryableWithHigherModel") === true ||
+        lower.includes("try with a higher model") ||
+        lower.includes("use a higher model") ||
+        lower.includes("use higher model") ||
+        lower.startsWith("file too large") ||
+        (lower.startsWith("document has") &&
+            lower.includes("page") &&
+            lower.includes("limit")));
+}
+function inferCategory(code, message, data) {
+    const lower = message.toLowerCase();
+    if (code === "UNAUTHORIZED")
+        return "authentication";
+    if (code === "TOO_MANY_REQUESTS")
+        return "rate_limit";
+    if (code === "NOT_FOUND")
+        return "not_found";
+    if (code === "CONFLICT")
+        return "conflict";
+    if (code === "NOT_IMPLEMENTED")
+        return "unsupported";
+    if (code === "INTERNAL_SERVER_ERROR")
+        return "server";
+    if (code === "UNPROCESSABLE_CONTENT") {
+        return data.userError === true ? "document_input" : "document_processing";
+    }
+    if (lower.includes("json schema") ||
+        lower.includes("invalid input") ||
+        lower.includes("invalid type") ||
+        lower.includes("expected")) {
+        return "validation";
+    }
+    return "document_input";
+}
+function inferOrigin(code, category, data) {
+    if (data.userError === true)
+        return "user";
+    if (code === "INTERNAL_SERVER_ERROR")
+        return "system";
+    if (category === "document_processing" && data.userError !== true)
+        return "system";
+    return "user";
+}
+function inferTitle(code, className, message) {
+    const lower = message.toLowerCase();
+    if (className === "FileTooLargeError")
+        return "File too large";
+    if (className === "PageLimitExceededError")
+        return "Page limit exceeded";
+    if (className === "PasswordProtectedError")
+        return "Password-protected document";
+    if (className === "UnsupportedFormatError")
+        return "Unsupported document format";
+    if (className === "URLFetchError")
+        return "Could not fetch document URL";
+    if (className === "InvalidDocumentURLError")
+        return "Invalid document URL";
+    if (className === "InvalidBase64Error")
+        return "Invalid base64 document";
+    if (className === "TierNotSupportedError")
+        return "Model does not support this file type";
+    if (className === "InvalidSchemaError")
+        return "Invalid JSON Schema";
+    if (className === "NoInputProvidedError")
+        return "No document input provided";
+    if (className === "EmptyDocumentError")
+        return "Empty document";
+    if (className === "NoTextDetectedError")
+        return "No readable text detected";
+    if (className === "ExtractionFailedError")
+        return "Extraction failed";
+    if (className === "AcademicPaperNotFoundError")
+        return "Paper not found";
+    if (className === "NoPublicPDFError")
+        return "No public PDF found";
+    if (lower.includes("no public pdf url"))
+        return "No public PDF found";
+    if (lower.includes("paper not found"))
+        return "Paper not found";
+    switch (code) {
+        case "BAD_REQUEST":
+            return "Invalid request";
+        case "UNAUTHORIZED":
+            return "Authentication failed";
+        case "NOT_FOUND":
+            return "Resource not found";
+        case "TOO_MANY_REQUESTS":
+            return "Rate limit exceeded";
+        case "CONFLICT":
+            return "Request conflict";
+        case "NOT_IMPLEMENTED":
+            return "Not implemented";
+        case "UNPROCESSABLE_CONTENT":
+            return "Document could not be processed";
+        case "INTERNAL_SERVER_ERROR":
+            return "PDF Vector server error";
+    }
+}
+function inferSuggestion(code, message, data) {
+    const lower = message.toLowerCase();
+    const requestId = readNumber(data, "requestId");
+    if (code === "UNAUTHORIZED") {
+        return "Check that the API key is present, valid, and belongs to the workspace you intend to use.";
+    }
+    if (code === "TOO_MANY_REQUESTS") {
+        const resetAt = readString(data, "resetAt");
+        return resetAt
+            ? `Wait until ${resetAt}, then retry the request.`
+            : "Wait for the rate limit window to reset, then retry the request.";
+    }
+    if (hasHigherModelHint(message, data)) {
+        const requestedModel = readString(data, "requestedModel");
+        return requestedModel
+            ? `Retry with a higher model than '${requestedModel}', or reduce the file size/pages before sending it again.`
+            : "Retry with a higher model, or reduce the file size/pages before sending it again.";
+    }
+    if (lower.includes("password-protected")) {
+        return "Remove the document password or upload an unlocked copy.";
+    }
+    if (lower.includes("json schema")) {
+        return "Fix the JSON Schema shape, then retry. Object schemas need properties, array schemas need items, and enum values must match their declared types.";
+    }
+    if (lower.includes("no public pdf url")) {
+        return "Provide a direct PDF URL or upload the paper file directly.";
+    }
+    if (lower.includes("url") ||
+        lower.includes("google drive") ||
+        lower.includes("docs returned an html page")) {
+        return "Use a direct, publicly fetchable document URL, or upload the file/base64 content instead.";
+    }
+    if (lower.includes("base64")) {
+        return "Send only the raw base64 document content, without a data URL prefix or invalid characters.";
+    }
+    if (lower.includes("unsupported format")) {
+        return "Convert the file to a supported format such as PDF, DOCX, XLSX, PPTX, CSV, TXT, HTML, or a supported image format.";
+    }
+    if (lower.includes("no input provided") || lower.includes("empty document")) {
+        return "Send exactly one document source: url, file, or base64, and make sure it is not empty.";
+    }
+    if (lower.includes("no readable text") ||
+        lower.includes("no text content") ||
+        lower.includes("document appears to be empty")) {
+        return "Upload a clearer scan or a source document with selectable/readable text.";
+    }
+    if (code === "NOT_FOUND") {
+        return "Check the identifier or URL and retry with a value that PDF Vector can resolve.";
+    }
+    if (code === "INTERNAL_SERVER_ERROR") {
+        return requestId
+            ? `Retry the request. If it keeps failing, contact support with requestId ${requestId}.`
+            : "Retry the request. If it keeps failing, contact support with the request details.";
+    }
+    if (code === "UNPROCESSABLE_CONTENT") {
+        return "Review the document quality and requested operation, then retry with clearer content or a simpler extraction prompt/schema.";
+    }
+    return "Fix the request and retry.";
+}
 export class PDFVectorError extends Error {
     code;
     status;
@@ -21,6 +206,15 @@ export class PDFVectorError extends Error {
     requestId;
     documentId;
     userError;
+    category;
+    origin;
+    title;
+    suggestion;
+    retryable;
+    retryableWithHigherModel;
+    requestedModel;
+    reasonCode;
+    supportMessage;
     constructor(options) {
         super(options.message, options.cause ? { cause: options.cause } : undefined);
         this.name = new.target.name;
@@ -29,7 +223,47 @@ export class PDFVectorError extends Error {
         this.data = options.data ?? {};
         this.requestId = readNumber(this.data, "requestId");
         this.documentId = readString(this.data, "documentId");
-        this.userError = this.data.userError === true;
+        this.category = inferCategory(this.code, this.message, this.data);
+        this.origin = inferOrigin(this.code, this.category, this.data);
+        this.userError = this.origin === "user";
+        this.title = inferTitle(this.code, this.name, this.message);
+        this.suggestion = inferSuggestion(this.code, this.message, this.data);
+        this.retryableWithHigherModel = hasHigherModelHint(this.message, this.data);
+        this.retryable =
+            this.retryableWithHigherModel ||
+                this.code === "TOO_MANY_REQUESTS" ||
+                this.code === "INTERNAL_SERVER_ERROR";
+        this.requestedModel = readString(this.data, "requestedModel");
+        this.reasonCode = readString(this.data, "code");
+        this.supportMessage = this.requestId
+            ? `PDF Vector request ${this.requestId} failed with ${this.code}: ${this.message}`
+            : `PDF Vector request failed with ${this.code}: ${this.message}`;
+    }
+    toAgentError() {
+        return {
+            name: this.name,
+            code: this.code,
+            status: this.status,
+            category: this.category,
+            origin: this.origin,
+            userError: this.userError,
+            title: this.title,
+            message: this.message,
+            suggestion: this.suggestion,
+            retryable: this.retryable,
+            retryableWithHigherModel: this.retryableWithHigherModel,
+            ...(this.requestId !== undefined ? { requestId: this.requestId } : {}),
+            ...(this.documentId !== undefined ? { documentId: this.documentId } : {}),
+            ...(this.reasonCode !== undefined ? { reasonCode: this.reasonCode } : {}),
+            ...(this.requestedModel !== undefined
+                ? { requestedModel: this.requestedModel }
+                : {}),
+            supportMessage: this.supportMessage,
+            data: this.data,
+        };
+    }
+    toJSON() {
+        return this.toAgentError();
     }
 }
 export class BadRequestError extends PDFVectorError {
@@ -50,10 +284,12 @@ export class NotFoundError extends PDFVectorError {
 export class TooManyRequestsError extends PDFVectorError {
     limit;
     resetAt;
+    retryAfterSeconds;
     constructor(options) {
         super({ ...options, code: "TOO_MANY_REQUESTS", status: 429 });
         this.limit = readNumber(options.data, "limit");
         this.resetAt = readString(options.data, "resetAt");
+        this.retryAfterSeconds = readNumber(options.data, "retryAfterSeconds");
     }
 }
 export class ConflictError extends PDFVectorError {
@@ -82,9 +318,15 @@ export class FileTooLargeError extends BadRequestError {
     model;
     constructor(options) {
         super(options);
-        this.fileSizeMB = readNumber(options.data, "fileSizeMB");
-        this.limitMB = readNumber(options.data, "limitMB");
-        this.model = readString(options.data, "model");
+        this.fileSizeMB =
+            readNumber(options.data, "fileSizeMB") ??
+                readNumberFromMatch(options.message, /file too large:\s*([\d.]+)\s*mb/i);
+        this.limitMB =
+            readNumber(options.data, "limitMB") ??
+                readNumberFromMatch(options.message, /exceeds the\s*([\d.]+)\s*mb limit/i);
+        this.model =
+            readString(options.data, "model") ??
+                readStringFromMatch(options.message, /for the '([^']+)' model/i);
     }
 }
 export class PageLimitExceededError extends BadRequestError {
@@ -93,9 +335,15 @@ export class PageLimitExceededError extends BadRequestError {
     model;
     constructor(options) {
         super(options);
-        this.pageCount = readNumber(options.data, "pageCount");
-        this.pageLimit = readNumber(options.data, "pageLimit");
-        this.model = readString(options.data, "model");
+        this.pageCount =
+            readNumber(options.data, "pageCount") ??
+                readNumberFromMatch(options.message, /document has\s*([\d.]+)\s*pages/i);
+        this.pageLimit =
+            readNumber(options.data, "pageLimit") ??
+                readNumberFromMatch(options.message, /exceeds the\s*([\d.]+)-page limit/i);
+        this.model =
+            readString(options.data, "model") ??
+                readStringFromMatch(options.message, /for the '([^']+)' model/i);
     }
 }
 export class PasswordProtectedError extends BadRequestError {
@@ -105,8 +353,12 @@ export class UnsupportedFormatError extends BadRequestError {
     supportedFormats;
     constructor(options) {
         super(options);
-        this.format = readString(options.data, "format");
-        this.supportedFormats = readString(options.data, "supportedFormats");
+        this.format =
+            readString(options.data, "format") ??
+                readStringFromMatch(options.message, /unsupported format \(([^)]+)\)/i);
+        this.supportedFormats =
+            readString(options.data, "supportedFormats") ??
+                readStringFromMatch(options.message, /supported formats:\s*(.+)$/i);
     }
 }
 export class URLFetchError extends BadRequestError {
@@ -116,26 +368,42 @@ export class URLFetchError extends BadRequestError {
     constructor(options) {
         super(options);
         this.url = readString(options.data, "url");
-        this.statusCode = readNumber(options.data, "statusCode");
-        this.statusText = readString(options.data, "statusText");
+        this.statusCode =
+            readNumber(options.data, "statusCode") ??
+                readNumberFromMatch(options.message, /document from url:\s*(\d{3})/i);
+        this.statusText =
+            readString(options.data, "statusText") ??
+                readStringFromMatch(options.message, /document from url:\s*\d{3}\s+(.+)$/i);
     }
 }
+export class InvalidDocumentURLError extends BadRequestError {
+}
+export class InvalidBase64Error extends BadRequestError {
+}
 export class TierNotSupportedError extends BadRequestError {
     documentType;
     model;
     allowedTypes;
     constructor(options) {
         super(options);
-        this.documentType = readString(options.data, "documentType");
-        this.model = readString(options.data, "model");
-        this.allowedTypes = readStringArray(options.data, "allowedTypes");
+        this.documentType =
+            readString(options.data, "documentType") ??
+                readStringFromMatch(options.message, /file type '([^']+)'/i);
+        this.model =
+            readString(options.data, "model") ??
+                readStringFromMatch(options.message, /for the '([^']+)' tier/i);
+        this.allowedTypes =
+            readStringArray(options.data, "allowedTypes") ??
+                readListFromMatch(options.message, /supported types:\s*(.+)$/i);
     }
 }
 export class InvalidSchemaError extends BadRequestError {
     reason;
     constructor(options) {
         super(options);
-        this.reason = readString(options.data, "reason");
+        this.reason =
+            readString(options.data, "reason") ??
+                readStringFromMatch(options.message, /invalid json schema:\s*(.+)$/i);
     }
 }
 export class NoInputProvidedError extends BadRequestError {
@@ -153,6 +421,28 @@ export class ExtractionFailedError extends UnprocessableContentError {
         this.rawText = readString(options.data, "rawText");
     }
 }
+export class AcademicPaperNotFoundError extends NotFoundError {
+    input;
+    paperErrorCode;
+    constructor(options) {
+        super(options);
+        this.input = readString(options.data, "input");
+        this.paperErrorCode = readString(options.data, "code");
+    }
+}
+export class NoPublicPDFError extends NotFoundError {
+    input;
+    paperTitle;
+    doi;
+    providerURL;
+    constructor(options) {
+        super(options);
+        this.input = readString(options.data, "input");
+        this.paperTitle = readString(options.data, "title");
+        this.doi = readString(options.data, "doi");
+        this.providerURL = readString(options.data, "providerURL");
+    }
+}
 const ORPC_CODE_TO_CLASS = {
     BAD_REQUEST: BadRequestError,
     UNAUTHORIZED: UnauthorizedError,
@@ -189,6 +479,11 @@ function selectSpecializedClass(code, message, data) {
             lower.startsWith("url did not return a supported document") ||
             lower.includes("returned an html page instead of a document"))
             return URLFetchError;
+        if (lower.startsWith("invalid document url") ||
+            lower.startsWith("document url must use"))
+            return InvalidDocumentURLError;
+        if (lower.startsWith("invalid base64-encoded string"))
+            return InvalidBase64Error;
         if (lower.startsWith("no input provided") ||
             lower.startsWith("empty document content"))
             return NoInputProvidedError;
@@ -205,6 +500,12 @@ function selectSpecializedClass(code, message, data) {
         if (data.hint !== undefined || data.rawText !== undefined)
             return ExtractionFailedError;
     }
+    if (code === "NOT_FOUND") {
+        if (data.code === "NO_PUBLIC_PDF" || lower.includes("no public pdf url"))
+            return NoPublicPDFError;
+        if (lower.startsWith("paper not found"))
+            return AcademicPaperNotFoundError;
+    }
     return ORPC_CODE_TO_CLASS[code];
 }
 export function fromORPCError(error) {
@@ -227,3 +528,6 @@ export function fromORPCError(error) {
 export function isPDFVectorError(error) {
     return error instanceof PDFVectorError;
 }
+export function isPDFVectorUserError(error) {
+    return error instanceof PDFVectorError && error.userError;
+}

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @pdfvector/instance-client
 
+## 0.0.51
+### Patch Changes
+
+
+
+- [#244](https://github.com/phuctm97/pdfvector/pull/244) [`d751cdd`](https://github.com/phuctm97/pdfvector/commit/d751cdde1c208c3298d1a0c2c34406e724e53264) Thanks [@khanhduyvt0101](https://github.com/khanhduyvt0101)! - Improve PDF Vector SDK error handling.
+
 ## 0.0.50
 ### Patch Changes
 

package/README.md

@@ -611,10 +611,14 @@ console.log(resultB.documentId); // "doc-b"
 
 ## Error Handling
 
-All API errors are thrown as `PDFVectorError` instances. The SDK transparently maps every server error into the most specific subclass it can, so you can branch on the type using `instanceof` and read typed metadata fields directly.
+All API errors are thrown as `PDFVectorError` instances. The SDK maps server errors into specific subclasses and adds user/agent-friendly fields such as `title`, `suggestion`, `userError`, retry flags, and `requestId`.
 
 ```typescript
-import { createClient, PDFVectorError } from "@pdfvector/instance-client";
+import {
+  PDFVectorError,
+  createClient,
+  isPDFVectorUserError,
+} from "@pdfvector/instance-client";
 
 const client = createClient({ apiKey: "your-api-key" });
 
@@ -624,35 +628,59 @@ try {
   });
   console.log(result.markdown);
 } catch (error) {
+  if (isPDFVectorUserError(error)) {
+    console.error(error.title);
+    console.error(error.suggestion);
+    return;
+  }
+
   if (error instanceof PDFVectorError) {
-    console.error(`API Error [${error.code}]: ${error.message}`);
-    console.error(`HTTP Status: ${error.status}`);
-    console.error(`Request ID: ${error.requestId}`);   // server-assigned, useful for support
-    console.error(`Document ID: ${error.documentId}`); // echoed back if you set one
-    console.error(`User error: ${error.userError}`);   // true if caused by your input
-  } else {
-    // Network errors (DNS, connection refused, timeout) bubble up as TypeError.
-    console.error("Unexpected Error:", error);
+    console.error(error.supportMessage);
+    console.error(error.toAgentError());
+    return;
+  }
+
+  // Network errors (DNS, connection refused, timeout) bubble up as TypeError.
+  console.error("Unexpected Error:", error);
+}
+```
+
+### User errors
+
+Use `isPDFVectorUserError(error)` or `error.userError` for caller-fixable failures that should usually be shown to the user instead of reported as system failures. For example, URL input failures such as `URL did not return a supported document` are `URLFetchError` instances with `userError: true`.
+
+```typescript
+import { isPDFVectorUserError, isPDFVectorError } from "@pdfvector/instance-client";
+
+try {
+  await client.document.parse({ url: "https://example.com/page.html" });
+} catch (error) {
+  if (isPDFVectorUserError(error)) {
+    console.error(error.suggestion);
+  }
+
+  if (isPDFVectorError(error) && error.retryableWithHigherModel) {
+    console.error("Retry with a stronger model or a smaller document.");
   }
 }
 ```
 
 ### Branching on specific error types
 
-Every error class extends `PDFVectorError`, so you can use `instanceof` to handle specific cases. Specialized subclasses expose typed fields pulled from the error's `data` payload:
+Every error class extends `PDFVectorError`, so you can use `instanceof` to handle specific cases. Specialized subclasses expose typed fields pulled from the error payload:
 
 ```typescript
 import {
-  createClient,
+  EmptyDocumentError,
+  ExtractionFailedError,
   FileTooLargeError,
+  InvalidSchemaError,
+  NoPublicPDFError,
   PageLimitExceededError,
   PasswordProtectedError,
-  URLFetchError,
-  UnauthorizedError,
   TooManyRequestsError,
-  EmptyDocumentError,
-  ExtractionFailedError,
-  PDFVectorError,
+  UnauthorizedError,
+  URLFetchError,
 } from "@pdfvector/instance-client";
 
 try {
@@ -664,14 +692,18 @@ try {
     );
   } else if (error instanceof PageLimitExceededError) {
     console.error(
-      `Document has ${error.pageCount} pages — ${error.model} only supports up to ${error.pageLimit}`,
+      `Document has ${error.pageCount} pages; ${error.model} supports up to ${error.pageLimit}`,
     );
   } else if (error instanceof PasswordProtectedError) {
     console.error("Remove the password from the file and try again");
   } else if (error instanceof URLFetchError) {
-    console.error(`Could not fetch ${error.url}: ${error.statusCode} ${error.statusText}`);
+    console.error(error.suggestion);
+  } else if (error instanceof InvalidSchemaError) {
+    console.error(error.reason);
+  } else if (error instanceof NoPublicPDFError) {
+    console.error("Provide a direct PDF URL or upload the paper file directly");
   } else if (error instanceof UnauthorizedError) {
-    console.error("Invalid API key — check your dashboard");
+    console.error("Invalid API key; check your dashboard");
   } else if (error instanceof TooManyRequestsError) {
     console.error(`Rate limit ${error.limit} exceeded; resets at ${error.resetAt}`);
   } else if (error instanceof EmptyDocumentError) {
@@ -679,34 +711,6 @@ try {
   } else if (error instanceof ExtractionFailedError) {
     console.error(`Extraction failed. Hint: ${error.hint}`);
     if (error.rawText) console.error(`Model output sample: ${error.rawText}`);
-  } else if (error instanceof PDFVectorError) {
-    // Catch-all for any error code not specifically handled
-    console.error(`API Error [${error.code}]: ${error.message}`);
-  }
-}
-```
-
-You can also branch on the error code if you prefer:
-
-```typescript
-try {
-  await client.document.parse({ url: "..." });
-} catch (error) {
-  if (error instanceof PDFVectorError) {
-    switch (error.code) {
-      case "UNAUTHORIZED":
-        console.error("Invalid API key");
-        break;
-      case "BAD_REQUEST":
-        console.error("Validation error:", error.message);
-        break;
-      case "UNPROCESSABLE_CONTENT":
-        console.error("Could not process document:", error.message);
-        break;
-      case "INTERNAL_SERVER_ERROR":
-        console.error(`Server error (requestId: ${error.requestId}):`, error.message);
-        break;
-    }
   }
 }
 ```
@@ -721,13 +725,17 @@ PDFVectorError
 │   ├── PasswordProtectedError
 │   ├── UnsupportedFormatError            — format, supportedFormats
 │   ├── URLFetchError                     — url, statusCode, statusText
+│   ├── InvalidDocumentURLError
+│   ├── InvalidBase64Error
 │   ├── TierNotSupportedError             — documentType, model, allowedTypes
 │   ├── InvalidSchemaError                — reason
 │   └── NoInputProvidedError
 ├── UnauthorizedError               (401)
 ├── NotFoundError                   (404)
+│   ├── AcademicPaperNotFoundError        — input, paperErrorCode
+│   └── NoPublicPDFError                  — input, paperTitle, doi, providerURL
 ├── ConflictError                   (409)
-├── TooManyRequestsError            (429) — limit, resetAt
+├── TooManyRequestsError            (429) — limit, resetAt, retryAfterSeconds
 ├── UnprocessableContentError       (422)
 │   ├── EmptyDocumentError
 │   ├── NoTextDetectedError
@@ -740,42 +748,36 @@ PDFVectorError
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `code` | `string` | The ORPC error code (`BAD_REQUEST`, `UNAUTHORIZED`, etc.) |
-| `status` | `number` | HTTP status code (400, 401, 404, 409, 422, 429, 500, 501) |
-| `message` | `string` | Human-readable error message |
-| `data` | `Record<string, unknown>` | Raw error payload from the server |
-| `requestId` | `number \| undefined` | Server-assigned request ID — include in support tickets |
+| `code` | `string` | API error code (`BAD_REQUEST`, `UNAUTHORIZED`, etc.) |
+| `status` | `number` | HTTP-style status code |
+| `title` | `string` | Short readable summary |
+| `message` | `string` | Server-provided error message |
+| `suggestion` | `string` | Recommended next action |
+| `category` | `string` | `authentication`, `validation`, `document_input`, `document_processing`, `rate_limit`, `not_found`, `conflict`, `unsupported`, or `server` |
+| `origin` | `"user" \| "system"` | Whether the failure is caller-fixable or likely server/provider-side |
+| `userError` | `boolean` | `true` for expected caller-fixable failures |
+| `retryable` | `boolean` | `true` when retrying may help |
+| `retryableWithHigherModel` | `boolean` | `true` when retrying with a stronger model or smaller document may help |
+| `requestId` | `number \| undefined` | Server-assigned request ID; include in support tickets |
 | `documentId` | `string \| undefined` | Echoed back if you passed `context.documentId` |
-| `userError` | `boolean` | `true` if the failure was caused by your input (vs. a server-side issue) |
-| `cause` | `unknown` | Original error (the underlying `ORPCError` from the wire) |
-
-### Type guard
-
-If you'd rather not import `PDFVectorError` just to do an `instanceof` check, use the `isPDFVectorError` guard:
-
-```typescript
-import { isPDFVectorError } from "@pdfvector/instance-client";
+| `reasonCode` | `string \| undefined` | More specific server reason when available, such as `NO_PUBLIC_PDF` |
+| `supportMessage` | `string` | Compact support/logging message |
+| `data` | `Record<string, unknown>` | Raw error payload from the server |
+| `cause` | `unknown` | Original underlying error |
 
-try {
-  await client.document.parse({ url: "..." });
-} catch (error) {
-  if (isPDFVectorError(error)) {
-    console.error(error.code, error.message, error.requestId);
-  }
-}
-```
+Use `error.toAgentError()` or `JSON.stringify(error)` when you need a serializable error object for logs, workflows, retry planners, or agent tool responses.
 
 ### Error Codes
 
 | Code | Status | Description |
 |------|--------|-------------|
-| `BAD_REQUEST` | 400 | Input validation failed (e.g., missing fields, invalid URL, file too large, page limit exceeded, invalid JSON Schema) |
+| `BAD_REQUEST` | 400 | Input validation failed, including invalid URLs, unsupported formats, file size limits, page limits, invalid base64, and invalid JSON Schema |
 | `UNAUTHORIZED` | 401 | Missing or invalid API key |
-| `NOT_FOUND` | 404 | Resource not found (e.g., academic paper ID, version) |
+| `NOT_FOUND` | 404 | Resource not found, including academic paper IDs and papers without public PDFs |
 | `CONFLICT` | 409 | Operation conflicts with the current state |
-| `UNPROCESSABLE_CONTENT` | 422 | Document could not be processed (empty, no readable text, extraction failed) |
+| `UNPROCESSABLE_CONTENT` | 422 | Document could not be processed, including empty documents, no readable text, and extraction failures |
 | `TOO_MANY_REQUESTS` | 429 | Rate limit exceeded |
-| `INTERNAL_SERVER_ERROR` | 500 | Server-side failure — capture the `requestId` for support |
+| `INTERNAL_SERVER_ERROR` | 500 | Server-side failure; capture the `requestId` for support |
 | `NOT_IMPLEMENTED` | 501 | Endpoint not available on this instance |
 
 ## TypeScript Support
@@ -786,6 +788,7 @@ The SDK is written in TypeScript and includes full type definitions:
 import {
   createClient,
   isPDFVectorError,
+  isPDFVectorUserError,
   // Base error class — all errors inherit from this
   PDFVectorError,
   // HTTP-aligned error categories
@@ -803,12 +806,16 @@ import {
   PasswordProtectedError,
   UnsupportedFormatError,
   URLFetchError,
+  InvalidDocumentURLError,
+  InvalidBase64Error,
   TierNotSupportedError,
   InvalidSchemaError,
   NoInputProvidedError,
   EmptyDocumentError,
   NoTextDetectedError,
   ExtractionFailedError,
+  AcademicPaperNotFoundError,
+  NoPublicPDFError,
   // Underlying ORPC error — re-exported for advanced use cases
   ORPCError,
 } from "@pdfvector/instance-client";
@@ -820,7 +827,10 @@ import type {
   ContractInputs,
   ContractOutputs,
   PDFVectorModel,
+  PDFVectorAgentError,
+  PDFVectorErrorCategory,
   PDFVectorErrorCode,
+  PDFVectorErrorOrigin,
 } from "@pdfvector/instance-client";
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pdfvector/instance-client",
-  "version": "0.0.50",
+  "version": "0.0.51",
   "type": "module",
   "description": "Official TypeScript/JavaScript SDK for PDF Vector API - Parse PDF/Word/Image/Excel documents to clean, structured markdown format and search academic publications across multiple databases",
   "license": "MIT",