Structured error raised or returned by PdfElixide operations.

Non-bang functions return {:error, %PdfElixide.Error{}}; bang functions raise the same struct (it is an exception). Match on :reason to handle specific failures:

case PdfElixide.Document.open(path) do
  {:ok, doc} -> doc
  {:error, %PdfElixide.Error{reason: :encrypted}} -> prompt_for_password()
  {:error, %PdfElixide.Error{reason: :invalid_pdf}} -> reject()
end

Reasons

• :encrypted — the PDF is encrypted and needs a password first.
• :wrong_password — the supplied password was rejected.
• :invalid_pdf — malformed or unparseable PDF data.
• :unsupported — an unsupported PDF version, feature, or filter.
• :not_found — a referenced object was not found.
• :out_of_range — the page index is outside the document.
• :io — an underlying IO error.
• :panic — the native library or upstream pdf_oxide panicked on this input, i.e. hit a bug rather than a condition it reports. The handle stays usable, but a panic partway through an operation can leave it holding partially updated state, so close/1 it and reopen if the error recurs.
• :lock_poisoned — the internal resource lock was poisoned. Should no longer occur: a native panic is contained before it can poison a lock and is reported as :panic instead.
• :closed — the handle was released with close/1.
• :other — any error not covered above; message is preserved verbatim.

:message is a human-readable description. :details is reserved for future structured payloads and is currently always nil.

Errors versus exceptions

This struct is reserved for PDF and runtime failures. A malformed argument raises instead, even from a non-bang function — FunctionClauseError when a guard rejects it (e.g. a negative page index) and ArgumentError when the native layer cannot decode it (e.g. a form field value that is not a tagged tuple) — because that is a bug in the calling code rather than a condition of the document.