Every rule below was traced to an enforcement point in source. Rules marked (delegated) are implemented in a referenced library (PdfAPI.Core or PdfApi.SyncFusionCore) but are enforced on this API's request path, so they are catalogued here with their true location.
POST v1/info/fields/exist, POST v1/info/fields/flatten
BR-PDFAPI-001 Null merge request bypasses the error envelope¶
Field
Value
Statement
A merge request body must not be null; the guard runs before the action's error envelope, so a null body fails as a framework error rather than a PdfResult
Trigger
POST v1/merge invoked with a null request body
Enforcement
Enforce.ArgumentNotNull(request, "request"), called outside the surrounding try block
Merge proceeds with default (non-PDF/A) options rather than failing
Source
PdfAPI\Controllers\v1\MergeController.cs
BR-PDFAPI-003 Processor selection by configuration¶
Field
Value
Statement
The PDF processor is selected per request from configuration: pdfapi.pdfservicetype == "activepdf" selects ActivePDF; any other value, including missing, selects Syncfusion
Trigger
Every controller constructor call to pdfServiceFactory.Create()
Enforcement
PdfServiceFactory.Create() lower-cases the configured value and switches on it; no validation, no failure path for an unrecognized value
Origin
api
Reached from
Every endpoint (constructor-time)
Outcome
Silent fallback to Syncfusion for any value other than the literal "activepdf"
PDF validity is determined by the %PDF- file signature; failure raises a PdfException reporting that the file is not a valid PDF document (exact message text is not visible in this repository — delegated to PdfAPI.Core\Services\PdfClientService.cs)
Trigger
Any operation that calls PdfClientService.ValidatePdf or IsPdf
POST v1/extract, POST v1/info/pages/count, POST v1/info/validate, POST v1/info/version
Outcome
PdfException on a non-PDF payload wherever this validation path is used; POST v1/info/validate alone returns false instead of throwing (BR-PDFAPI-005 via IsPdf)
Source
PdfAPI.Core\Services\PdfClientService.cs
BR-PDFAPI-006 Merge aborts entirely on pre-conversion failure¶
Field
Value
Statement
In a merge, every non-PDF input is converted to PDF first; if any pre-conversion fails, a PdfException is thrown and the whole merge is abandoned — no partial output is produced
Trigger
POST v1/merge with one or more non-PDF input documents
When PDF/A output is requested but the produced document fails PDF/A validation, the result is silently downgraded to PdfFormat.Pdf rather than failing the request
Trigger
POST v1/merge with Options.IsPdfa == true and the merged output fails ValidatePdfA
Enforcement
Conditional downgrade in SyncfusionPdfService.Merge
BR-PDFAPI-008 Unsupported extension leaves status at default¶
Field
Value
Statement
An unrecognized source file extension yields a failure result with message "Unsuppported extension ({ext})" (spelling as in source). The result's Status is left at the enum default NotTracked, not Failed — a caller checking Status == Failed will not detect this case
Trigger
POST v1/convert / POST v1/convert/{fileExtension} with an unrecognized extension
Enforcement
Extension dispatch switch in ConverterFactory.Convert
A tracked request moves SCHED → PROC → terminal (SUCC / ERROR / CANCE / ABORT); these persisted codes map onto the PdfStatus enum
Trigger
Any tracked convert/merge/extract request
Enforcement
Status transitions in PdfTrackingService
Origin
api
Reached from
All tracked endpoints
Outcome
Consistent status vocabulary between the persisted tracking row and PdfStatus returned to callers
Source
PdfAPI\Services\PdfTrackingService.cs
BR-PDFAPI-012 Tracking degrades gracefully without a unit of work¶
Field
Value
Statement
When tracking is unavailable (no unit of work), every tracking operation degrades gracefully and returns a non-tracked result instead of failing the request
Trigger
_uow == null at the point a tracking operation is invoked
Enforcement
if (_uow == null) guard on every method in PdfTrackingService
Origin
api
Reached from
All tracking operations
Outcome
Requests continue to succeed functionally even when tracking persistence is unavailable
Source
PdfAPI\Services\PdfTrackingService.cs
BR-PDFAPI-013 Download requires succeeded status and output path¶
Field
Value
Statement
A tracked document is downloadable only when its status is Succeeded and a non-null output file path is recorded; otherwise an explanatory failure result is returned with HTTP 200
Trigger
GET v1/legacy/download/{trackingId}
Enforcement
Status/path check in PdfTrackingService.DownloadByTrackingId
A status check polls while the status is Scheduled or Processing, sleeping retryIntervalMilliseconds between reads, up to retryCount attempts; the default retryCount = 0 makes it a single read
Trigger
GET v1/info/track/{trackingId}
Enforcement
Polling loop in PdfTrackingService.CheckPdfTrackingStatus
A failed request sends an incident email only when the caller set SendHeatEmailOnFailure; the subject is taken from the tracking record's ApplicationError.HeatEmailSubject
Trigger
Convert/merge/extract failure with SendHeatEmailOnFailure = true
Enforcement
PdfService.SendIncidentEmail, invoked from FinalizeResult
Origin
api
Reached from
POST v1/convert, POST v1/convert/{fileExtension}, POST v1/merge, POST v1/extract
Outcome
Conditional outbound SMTP email on failure, addressed and subjected from configuration/tracking data
When pdfapi.saveInputToTemp is enabled, the inbound source document is written to temporary storage before processing
Trigger
Any convert/merge/extract request when the setting is true
Enforcement
Conditional write in PdfService and its use sites
Origin
api
Reached from
POST v1/convert, POST v1/convert/{fileExtension}, POST v1/merge, POST v1/extract
Outcome
Extra disk I/O and a temporary copy of every submitted document when enabled
Source
PdfAPI\Services\PdfService.cs:30
BR-PDFAPI-017 Processing failures return 200 with a PdfResult¶
Field
Value
Statement
For convert, extract, merge, and download, a processing failure is not an HTTP failure: the exception is logged and returned as a PdfResult carrying a message, with status code 200. Callers must inspect the payload
Trigger
Any handled exception inside the per-action try/catch on these four controllers
Page ranges are clamped to the document's page count, out-of-range ranges are skipped rather than erroring, descending ranges extract pages in reverse order, and a single IsOriginal range returns the original file untouched
Trigger
POST v1/extract with one or more page ranges
Enforcement
Range-handling logic in PageRange and PdfExtractor.Extract
On the ActivePDF processor, a PDF/A production failure is retried as plain PDF, and configured error codes (pdfApi.ErrorsToRetry) trigger a retry of the whole operation
Trigger
ActivePDF processor conversion/merge failure matching a configured retryable error code, or a PDF/A production failure
Enforcement
Retry logic in ActivePdfService
Origin
api
Reached from
POST v1/convert, POST v1/convert/{fileExtension}, POST v1/merge (ActivePDF processor only)
Outcome
Transient ActivePDF failures are retried automatically; PDF/A failures fall back to plain PDF
Source
PdfAPI\Services\ActivePdf\ActivePdfService.cs
BR-PDFAPI-021 Form field inspection client selection¶
Field
Value
Statement
Form-field inspection and flattening default to the iTextSharp client implementation (useClient = true) and use the Syncfusion helper only when the caller explicitly opts out
Trigger
POST v1/info/fields/exist or POST v1/info/fields/flatten
Enforcement
useClient parameter branch in InfoController and PdfService
Note: Statements marked with * were inferred from code structure, naming conventions, or
contextual evidence where direct confirmation was not available in source artifacts. Statements
marked with ** could not be confirmed; treat as unknown until verified.