@pdfvector/instance-client 0.0.49 → 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,18 @@
 # @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
+
+- Updated dependencies [[`2c8691c`](https://github.com/phuctm97/pdfvector/commit/2c8691c9bbd251ff7b7a153fd4254d9360c11c08)]:
+  - @pdfvector/instance-contract@0.0.47
+
 ## 0.0.49
 ### Patch Changes
 

package/README.md

@@ -1,6 +1,6 @@
 # PDF Vector TypeScript/JavaScript SDK
 
-The official TypeScript/JavaScript SDK for the [PDF Vector](https://www.pdfvector.com) API: Parse PDF, Word, Image, and Excel documents to clean, structured markdown format, ask questions about documents using AI, extract structured data from documents with JSON Schema, search across multiple academic databases with a unified API, fetch specific publications by DOI, PubMed ID, ArXiv ID, and more, find relevant academic citations for paragraphs of text, explore paper citation graphs, find similar papers, and search for research grants across US, EU, and UK funding databases.
+The official TypeScript/JavaScript SDK for the [PDF Vector](https://www.pdfvector.com) API: Parse PDF, Word, Image, and Excel documents to clean, structured markdown format, ask questions about documents using AI, extract structured data from documents with JSON Schema, search across multiple academic databases with a unified API, fetch specific publications by DOI, PubMed ID, ArXiv ID, and more, convert academic paper IDs or provider URLs to markdown, find relevant academic citations for paragraphs of text, explore paper citation graphs, find similar papers, and search for research grants across US, EU, and UK funding databases.
 
 ## Installation
 
@@ -380,6 +380,36 @@ result.errors?.forEach((error) => {
 
 **Supported ID types:** DOI, PubMed ID, ArXiv ID, Semantic Scholar ID, ERIC ID, Europe PMC ID, OpenAlex ID.
 
+### Parse Academic Paper to Markdown
+
+Resolve a paper ID or provider URL to its public PDF and parse it into markdown. Uses the same per-page model pricing as Document Parse.
+
+```typescript
+const result = await client.academic.parse({
+  id: "1706.03762", // DOI, PubMed ID, ArXiv ID, Semantic Scholar ID, or provider URL
+  model: "auto",    // "auto" | "nano" | "mini" | "pro" | "max"
+});
+
+console.log(`Title: ${result.title}`);
+console.log(`Provider: ${result.detectedProvider}`);
+console.log(`PDF: ${result.pdfURL}`);
+console.log(result.markdown);
+console.log(`Pages: ${result.pageCount}, Credits: ${result.credits}`);
+```
+
+You can pass a provider URL instead of an ID:
+
+```typescript
+const result = await client.academic.parse({
+  url: "https://arxiv.org/abs/1706.03762",
+  model: "nano",
+});
+
+console.log(result.markdown);
+```
+
+Provide exactly one of `id` or `url`. If the paper cannot be found, has no public PDF, or the resolved PDF cannot be fetched, the API returns a typed `PDFVectorError` with a clear message and no parse credits are charged.
+
 ### Find Citations for a Paragraph
 
 Find relevant academic citations for each sentence in a paragraph using semantic similarity. Costs 2 credits per sentence analyzed.
@@ -573,6 +603,7 @@ console.log(resultB.documentId); // "doc-b"
 | Bank Statement Extract | 6 | 10 | 14 | 18 | /page |
 | Academic Search | 2 | 2 | 2 | 2 | /request |
 | Academic Fetch | 2 | 2 | 2 | 2 | /request |
+| Academic Parse | 1 | 2 | 4 | 8 | /page |
 | Academic Find Citations | 2 | 2 | 2 | 2 | /sentence |
 | Academic Paper Graph | 2+ | 2+ | 2+ | 2+ | /request |
 | Academic Similar Papers | 3 | 3 | 3 | 3 | /request |
@@ -580,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" });
 
@@ -593,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 {
@@ -633,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) {
@@ -648,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;
-    }
   }
 }
 ```
@@ -690,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
@@ -709,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
@@ -755,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
@@ -772,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";
@@ -789,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.49",
+  "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",
@@ -33,7 +33,7 @@
   },
   "main": ".tsc/lib/index.js",
   "dependencies": {
-    "@pdfvector/instance-contract": "^0.0.46"
+    "@pdfvector/instance-contract": "^0.0.47"
   },
   "files": [
     ".tsc",