錯誤參考

這是 NextPDF Core 所拋出例外狀況的參考清單，依領域分門別類。每個分類頁面都會逐一說明各個類別在何時被拋出、攜帶哪些結構化資料，以及如何復原。如果你診斷的是某個症狀，而非要攔截某個特定類別，請改從疑難排解指南開始——這些指南是依你所觀察到的現象來組織的。

概覽

大多數例外狀況都繼承自單一基底類別 NextPdfException，因此你可以用一個 catch 區塊攔截整個家族。
NextPdfException 具備**脈絡感知（context-aware）**能力：它實作了 ContextAwareExceptionInterface，該介面宣告了 getContext(): array。許多子類別會覆寫 getContext() 以回傳結構化的診斷鍵；其他子類別則沿用空的預設值，並透過訊息與具型別的 getter 揭露細節。
少數低階例外狀況直接繼承 PHP 的 \RuntimeException，而非 NextPdfException。這些不具脈絡感知能力，並將細節攜帶在公開的 readonly 屬性上。每個分類頁面都會明確標示它們。
兩個名為 …Violation 的合規型別（ComplianceViolation、RuleViolation）是值物件（value object），而非例外狀況——它們描述一項發現，但不會被拋出。

基底型別與脈絡合約

NextPdfException 是一個抽象類別，繼承自 \RuntimeException 並實作 ContextAwareExceptionInterface。這份合約很精簡：

interface ContextAwareExceptionInterface
{
    /** @return array<string, mixed> structured, log-safe diagnostic context */
    public function getContext(): array;
}

因此，一個具防禦性的處理器看起來像這樣：

use NextPDF\Exception\NextPdfException;

try {
    // … NextPDF operation …
} catch (NextPdfException $e) {
    $logger->error($e->getMessage(), $e->getContext());
    // getContext() returns [] when a subclass does not override it;
    // the message and any typed getters still carry the detail.
}

由於某些失敗會以裸的 \RuntimeException 浮現（請參見各分類的註記），一個層層防護的邊界可能也會攔截 \RuntimeException 並檢視其具體型別。

另請參閱

疑難排解 — 以症狀組織的指南，涵蓋簽章驗證、加密與權限、字型與標記，以及 PDF/A 與 PDF/UA 驗證。