When a document doesn't fit

Your values can make a document that doesn’t lay out: a name too long for its frame, say. In the editor a designer sees it at once; in an API render nobody does, so the template’s policy decides what happens. Set it on the template, or in a single request over the template’s: the same settings, at the top of the request.

Setting	Values	What it does
onErrors	fail (default)	Refuse the render: 422 layout-errors, every problem listed, nothing kept.
	diagnostic	Refuse it the same way, and keep a PDF marked with the problems, to look at.
	render	Make the document anyway when every error is text that doesn’t fit (the text is cut at its frame); refuse any other error.
failOnWarnings	warning codes	Treat these warnings as errors.
requirePdfx	true	Refuse a print PDF that fails PDF/X-4 preflight, instead of making it without the claim.

Some problems are never rendered past, whatever the policy: values that break the contract, unknown resources and font rights.

Set a template’s policy

curl -X PATCH -H "Authorization: Bearer $PAPRIKA_KEY" -H "Content-Type: application/json" -d '{"policy": {"onErrors": "render"}}' "$PAPRIKA_URL/v1/templates/tpl_9fK2mQ7rLx4VbN1s"

It applies to every version and replaces the template’s earlier policy whole.

Read a refusal

The template now renders past text that doesn’t fit; this request asks for the default, fail, and a name too long for the badge:

curl -H "Authorization: Bearer $PAPRIKA_KEY" -H "Content-Type: application/json" -H "Accept: application/pdf" -d '{"values": {"name": "Professor Dame Stephanie Shirley of Chalfont St Giles, Founder", "role": "Speaker"}, "onErrors": "fail"}' "$PAPRIKA_URL/v1/templates/tpl_9fK2mQ7rLx4VbN1s/versions/latest/render"

Each problem names the page, the frame and the fields that frame shows, so you know which values to correct:

{
  "code": "layout-errors",
  "message": "The document has 1 problem its policy doesn't render past; see errors",
  "errors": [
    {
      "page": 1,
      "frame": "text",
      "code": "text-overflow",
      "message": "Text cannot fit within the frame growth limits",
      "fields": ["name"]
    }
  ],
  "warnings": [],
  "requestId": "3bc05084"
}

Check before rendering

A dry run lays the values out and judges them by the policy, without rendering or keeping anything:

curl -H "Authorization: Bearer $PAPRIKA_KEY" -H "Content-Type: application/json" -d '{"name": "Grace Hopper", "role": "Keynote speaker"}' "$PAPRIKA_URL/v1/templates/tpl_9fK2mQ7rLx4VbN1s/versions/latest/validate?layout=true"

{ "valid": true, "version": 1, "warnings": [] }