Warnings

The rendering pipeline follows one policy: a value that cannot be rendered never fails the document. The affected value is skipped and the skip is reported as a warning with a stable code. A hearing notice goes out with a substituted character rather than not going out at all, and your integration still finds out.

When your workflow demands the opposite trade-off, turn warnings into errors per request.

How warnings are reported

JSON responses

JSON responses carry a warnings array:

{
  "files": [ … ],
  "warnings": [
    { "code": "ASSET_NOT_FOUND", "message": "image field references deleted asset 2c9e5b7a-…" }
  ]
}

Binary responses

Binary responses (the PDF itself is the body) carry headers:

Header	Content
X-Warning-Count	Total number of warn-and-skip events; absent when zero
X-Warnings	JSON array of {code, message} objects (capped at 4 KB, so the count may exceed the entries listed)

A warning-free response carries neither header. Log both channels in your integration: warnings are the only signal that a document rendered differently than the data intended.

Warnings also appear in version create/finalize responses (for example FIELD_OUT_OF_BOUNDS when a field lies outside its page).

Turning warnings into errors

"on_warning": "error" on a generate or document request fails with 422 GENERATION_WARNINGS instead of returning a document that produced warnings:

{ "data": { … }, "on_warning": "error" }

Use it when a skipped value would make the document legally wrong. For tables, prefer the targeted overflow: "error" control.

Warning code registry

Codes are stable; the set is open: new codes may be added.

Text and symbols

Code	Meaning
TEXT_SUBSTITUTED	Characters outside the supported character set were replaced with ? (see International text)
SYMBOL_NOT_ENCODABLE	A symbol glyph isn't in the supported set; the field was skipped
UNICODE_MISSING_GLYPHS	Unicode mode couldn't find glyphs for some code points
DIRECTION_REQUIRES_UNICODE	typography.direction was set without Unicode mode

Form fills

Code	Meaning
FILL_UNKNOWN_FIELD	No form field with that name exists in the base PDF (check acro_fields)
FILL_NOT_ENCODABLE	The fill value contains characters the form field can't hold
FILL_OPTION_MISMATCH	The value doesn't exactly match any of the dropdown/option-list choices
FILL_UNSUPPORTED_KIND	The target form field's kind can't be filled
FILL_FAILED	The fill could not be applied
APPEARANCES_STALE	A filled value may display only after the viewer regenerates field appearances

Layout and media

Code	Meaning
FIELD_OUT_OF_BOUNDS	A field's box lies outside its page (reported at version create/finalize)
ASSET_NOT_FOUND	An image field references a deleted or unknown asset
BARCODE_INVALID	The value can't be encoded in the chosen symbology
TABLE_ROWS_TRUNCATED	Rows beyond the table box's capacity were dropped

HTML

Code	Meaning
HTML_CONTENT_SANITIZED	Disallowed HTML (scripts, frames, forms, fetching content) was removed
HTML_FIELD_TRUNCATED	An html field's content overflowed its box and was cut to fit

Practices

• Treat any warning on an issued document as a review signal; alert on TEXT_SUBSTITUTED and FILL_* codes especially: they mean the output differs from the source data.
• In development, run with "on_warning": "error" to surface every rendering gap early; relax to the default for production issuance if availability matters more.
• Warnings are per-request. Fix the cause (declare the merge tag, re-upload the asset, switch to Unicode mode) rather than suppressing the signal.