Problem

An error as RFC 9457 problem details. type, title, status, detail, code and request_id are always there; the other members appear only with the codes their descriptions name, and a new member may be added to a problem at any time.

typestring<uri>required

The page that explains this error.

Example: https://docs.formfeed.dev/errors/template-syntax

titlestringrequired

Short title of the error code.

Example: Template syntax error

statusintegerrequired

Example: 422

detailstringrequired

What went wrong in this request, in English.

codestringrequired

The stable error code; branch on this, not on title or detail.

Possible values: [template_not_found, template_syntax_error, template_runtime_error, data_validation_error, navigation_failed, render_timeout, page_limit_exceeded, output_too_large, file_too_large, source_not_found, source_invalid, source_encrypted, tool_failed, file_type_unsupported, office_document_invalid, office_document_too_large, office_conversion_failed, office_unavailable, unsupported_in_office, test_output_unavailable, einvoice_data_invalid, einvoice_profile_unsupported, einvoice_display_mismatch, pdfa_conversion_failed, conformance_unavailable, pdfua_validation_failed, quota_exceeded, rate_limited, region_unavailable, worker_exhausted, invalid_request, unauthorized, forbidden, not_found, conflict, not_implemented, schema_breaking_change, channel_not_found, channel_name_invalid, channel_in_use, render_input_expired, listen_session_limit, listen_session_ended, last_workspace, storage_not_configured, storage_test_failed]

location objectnullable

Problems of a render: line and column for a template error, part and paragraph for an office template, otherwise null. Absent on problems raised before anything rendered.

lineinteger

Template errors: the line in the template source, from 1.

columninteger

The column, from 1.

partstring

Office templates: the part of the file (document, header, footer, slide).

Example: word/document.xml

paragraphinteger

Office templates: the paragraph within the part, from 1.

request_idstringrequired

The id of this request, also in the X-Request-Id header; quote it when you contact support. An X-Request-Id you send (up to 255 letters, digits, _, - and =) is used as it is.

Example: req_7c1e9a3b5d0f4e2a8c6b1d3e5f

errors object[]

data_validation_error: every place where the data does not match the schema. einvoice_data_invalid, when the _invoice block itself is refused: every field that is missing or breaks a rule.

Array [

pathstringnullable

Example: data.invoice.number

messagestring

Example: data.invoice.number: must be string

rulestring

einvoice_data_invalid only: the rule of EN 16931 or of the French specifications the field breaks.

Example: BR-CO-15

]

einvoice object

The report of a render whose e-invoice failed validation or the display check (einvoice_data_invalid, pdfa_conversion_failed, einvoice_display_mismatch); the same object the render carries as einvoice. Also on pdfua_validation_failed where the render made an e-invoice: the invoice was valid and its file failed PDF/UA-1.

profilestring

Possible values: [basic, en16931]

flavourstring

Possible values: [factur-x, zugferd]

spec_versionstring

The release of the specification the file was written and validated for, under the name of flavour: Factur-X 1.09 is ZUGFeRD 2.5.

Example: 1.09

xml_urlstring<uri>nullable

A link to the XML, made like the render's download_url (signed, or the plain URL of a public output), when the render asked for xml: both and the file is still stored. The XML is inside the PDF either way.

validation objectnullable

What the validator said about the file. Null only when the render failed before it ran.

validboolean

No finding of severity error. A render succeeds only with a valid file.

schematronstring

The rule set the XML was held to, as it names itself, and the validator that ran it.

Example: Factur-X 1.09.2 (Mustang 2.26.0)

pdfastringnullable

The PDF/A flavour the file was checked against; null when validation ended at the XML.

Example: PDF/A-3b

messages object[]

At most 50, errors first.

Array [

partstring

Whether the finding is about the invoice XML or about the PDF/A file.

Possible values: [xml, pdf]

severitystring

Possible values: [error, warning]

rulestringnullable

The rule: of EN 16931 (BR-…), of the syntax binding (CII-SR-…), a code of the XML schema (cvc-…), or the clause of PDF/A (6.2.11.4.1-1). Null where the validator names none.

Example: BR-CO-25

messagestring

locationstringnullable

Where: an XPath into the XML (a line item always carries its index), a line and column for a finding of the XML schema, or the object of the PDF.

]

truncatedboolean

Present and true when there were more findings than messages holds.

idstring<uuid>

The validator's own id for this report. Quote it when you ask about a render; renders before 9 October 2026 have none.

Example: 6f2c7e9a-1d4b-4c3e-8a5f-2b7d9e0c1a34

versions object

The versions of the validator's parts that judged the file. The pinned versions are listed in the documentation.

property name*string

xml_sha256string

SHA-256 of the XML that was judged: the XML inside the PDF, and the file xml_url links.

Example: 3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b

pdf_sha256stringnullable

SHA-256 of the PDF that was judged. For a render that succeeded it is the delivered file and equals the render's output_sha256; null where the validator refused the XML before there was a converted file.

Example: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

display objectnullable

The display check: the values of the XML that were looked for in the text of the PDF, by their business term in EN 16931.

checkedstring[]

Example: ["BT-1","BT-109","BT-110","BT-112"]

missingstring[]

The terms the PDF does not show. Zero amounts are not looked for.

Example: []

accessibility object

The rules of PDF/UA-1 the file failed, each with the elements of the template it is about; the same object the render carries as accessibility. On pdfua_validation_failed, and on einvoice_display_mismatch where the render also set settings.pdf.ua.

standardstring

Possible values: [PDF/UA-1]

checkstring

Possible values: [strict, report]

conformantboolean

The file passed every rule the validator checks. Only then does it carry the PDF/UA identifier.

validatorstring

The validator and its version. Its rule set moves between releases.

Example: veraPDF 1.30.2

rules object

passedinteger

Example: 106

failedinteger

Example: 0

failures object[]

The rules the file failed, at most 20.

Array [

rulestring

Clause and test number of the rule in veraPDF's PDF/UA-1 profile.

Example: 7.4.2-1

codestring

What in the template the rule is about, where the template check found it. Absent for a rule it has no finding for.

Possible values: [document-title, image-alt, figure-name, heading-order, table-rows, table-cell-empty, masked-text]

countinteger

How many checks of the rule failed.

messagestring

What to change in the template, else the validator's own description of the rule.

Example: This h3 follows an h1, so a heading level is skipped. Make it an h2 and size it with CSS.

elementsstring[]

The start tags of the elements concerned, at most five.

Example: ["<h3>"]

]

warnings object[]

What a reader will stumble over although no rule fails for it.

Array [

codestring

Possible values: [filtered-text, document-language, table-headers, link-name, generated-text, fixed-text, running-text]

countinteger

elementsstring[]

Start tags, or the text itself for running-text and generated-text; at most five.

]

truncatedboolean

Present and true when more rules failed than failures holds.

indexinteger

The position, from 0, of what the problem is about: the item of a batch, or the source of a PDF tool or of post.merge_after.

issues object[]

invalid_request: each place of the body or query that failed its check.

Array [

pathstringrequired

Dotted path into the body; empty for the body as a whole.

Example: items.0.data

messagestringrequired

]

fieldstring

The field of the request the problem is about (invalid_request, source_not_found, source_invalid, storage_not_configured, einvoice_profile_unsupported).

Example: post.watermark.image

featurestring

What the plan does not allow or holds no more of: with forbidden, and with invalid_request for the 1,000 files of a library (files) and the 200 shared partials of an organisation (partials).

Possible values: [byo_storage, canary, channels, einvoice, files, office, partials, post_processing, templates, webhooks]

planstring

The plan that refused (forbidden of a plan gate, test_output_unavailable).

Example: free

limitinteger

The number that was reached: a count of the plan with forbidden (templates, channels, webhook endpoints, test e-invoices a day), the bucket of rate_limited, or bytes with file_too_large, office_document_too_large and a shared partial that is too large.

usedinteger

forbidden with feature: einvoice: the test e-invoices made today.

resets_atstring<date-time>

forbidden with feature: einvoice: the next midnight UTC, when the day's test e-invoices start again.

window_secondsinteger

rate_limited: the window of the bucket that is empty, 1 for the plan's requests per second, 60 for the Free test keys' minute.

bytesinteger

The size that was refused (file_too_large, office_document_too_large, a shared partial that is too large).

partialsstring[]

The shared partials a render included when they were too large together (invalid_request).

allowedOutputFormat[]

The outputs the template's kind can make (invalid_request with field: output), or the one a test render on the plan can (test_output_unavailable).

Possible values: [pdf, png, jpg, webp, docx, pptx]

outputOutputFormat

The output that was asked for (test_output_unavailable, and invalid_request for settings.pdf.ua on an image).

Possible values: [pdf, png, jpg, webp, docx, pptx]

templatestring

The template as the request named it (channel_not_found, invalid_request of validate_data).

channelstring

The channel as the request named it (channel_not_found, channel_name_invalid).

breaking object[]

schema_breaking_change: the changes that break callers.

Array [

pathstringrequired

Dotted field path; items[] for array elements, empty for the data itself.

Example: customer.email

pointerstringrequired

Example: /properties/customer/properties/email

kindstringrequired

Possible values: [field-added-required, field-added-optional, field-removed, field-became-required, field-became-optional, type-narrowed, type-widened, enum-values-removed, enum-values-added, enum-added, enum-removed, const-changed, constraint-tightened, constraint-relaxed, additional-properties-closed, additional-properties-opened, keyword-changed]

breakingbooleanrequired

messagestringrequired

Example: "customer.email" is now required

]

safe object[]

schema_breaking_change: the changes that do not.

Array [

pathstringrequired

Dotted field path; items[] for array elements, empty for the data itself.

Example: customer.email

pointerstringrequired

Example: /properties/customer/properties/email

kindstringrequired

breakingbooleanrequired

messagestringrequired

Example: "customer.email" is now required

]

current objectnullable

conflict of PUT /partials/{name}: the stored partial, null when it was deleted.

namestringrequired

Example: letterhead

engineEnginerequired

The template language: Jinja2 (Nunjucks), Liquid or Handlebars.

Possible values: [jinja2, liquid, handlebars]

descriptionstringnullable

versionintegerrequired

Grows when the source or the engine changes.

Example: 3

sourcestring

Only in GET /partials/{name} and PUT responses.

created_atstring<date-time>required

updated_atstring<date-time>required

period_endstring<date>

quota_exceeded: the first day after the billing period.

hard_cap_unitsinteger

quota_exceeded at the hard cap: the units at which overage stops renders.

render_idstring

The render the problem is about: the one that failed, once a synchronous render has its row or when GET /renders/{id}/result answers its failure; with source_not_found and source_invalid, the source render.

Example: rnd_7da09ab6cd9946b798c187c2a9350852

failing_itemsinteger

data_validation_error of a batch: how many items do not fit their schema.

page_countinteger

page_limit_exceeded: the pages the document has.

reasonstring

What the converter or validator said (source_invalid, office_conversion_failed, pdfa_conversion_failed, tool_failed).

entrystring

The part of an office file the problem is about (office_document_invalid, office_document_too_large, file_type_unsupported, source_encrypted).

Example: word/document.xml

entriesinteger

office_document_invalid: the number of parts of a file with too many.

methodinteger

office_document_invalid: a compression method of the file that is not supported.

formatstring

file_type_unsupported of a template upload: the format the file turned out to be.

kindstring

file_type_unsupported of a template upload: the kind the template has.

Possible values: [docx, pptx]

valuestring

einvoice_profile_unsupported: the value that was refused.

namestring

The file or partial name the problem is about (invalid_request).

content_typestringnullable

invalid_request of an upload: the type that was sent or detected.

filestring

source_invalid of a watermark: the library file that is no PNG or JPEG.

Example: fil_5b0000000000400080000000000000a1

client_idstring

forbidden for a connected agent: the OAuth client that may not do this.

rolestring

forbidden for a signed-in member: the role that may not do this.

request_data_retentionstring

render_input_expired: how long the workspace keeps render requests.

Possible values: [off, 24h, 7d]

error object

storage_test_failed: what the bucket answered.

codestring

Example: AccessDenied

http_statusintegernullable

Example: 403

messagestring

Example: Access Denied

keystring

storage_test_failed: the key of the test object.

connection object

storage_test_failed of POST /workspaces/{id}/storage/test: the connection as it stands now.

idstring<uuid>

workspace_idstring<uuid>

providerstring

Possible values: [s3, r2, s3_compatible]

endpointstring<uri>

The service address; derived from the region for s3 and from the account id for r2.

regionstringnullable

account_idstringnullable

jurisdictionstringnullable

Possible values: [default, eu]

bucketstring

prefixstring

force_path_styleboolean

key_templatestring

environmentsstring[]

Possible values: [live, test]

public_base_urlstringnullable

statusstring

active copies outputs; paused does not (see paused_reason).

Possible values: [active, paused]

paused_reasonstringnullable

failures: five permanent failures in a row (test the connection again to resume); plan: the plan no longer includes bring your own storage; workspace_deleted: the workspace was deleted and its credentials destroyed.

Possible values: [failures, workspace_deleted, plan]

access_key_hintstringnullable

The last four characters of the access key id.

Example: 7QX2

last_tested_atstring<date-time>nullable

last_error objectnullable

The provider's answer, reduced: its code, the HTTP status and the first line of its message.

codestring

Example: AccessDenied

http_statusintegernullable

Example: 403

messagestring

Example: Access Denied

created_atstring<date-time>

updated_atstring<date-time>

paused_reasonstring

conflict of a redelivery: why the connection is paused.

Possible values: [failures, workspace_deleted, plan]

property name*any

Problem
{
  "type": "https://docs.formfeed.dev/errors/template-syntax",
  "title": "Template syntax error",
  "status": 422,
  "detail": "string",
  "code": "template_not_found",
  "location": {
    "line": 0,
    "column": 0,
    "part": "word/document.xml",
    "paragraph": 0
  },
  "request_id": "req_7c1e9a3b5d0f4e2a8c6b1d3e5f",
  "errors": [
    {
      "path": "data.invoice.number",
      "message": "data.invoice.number: must be string",
      "rule": "BR-CO-15"
    }
  ],
  "einvoice": {
    "profile": "basic",
    "flavour": "factur-x",
    "spec_version": "1.09",
    "xml_url": "string",
    "validation": {
      "valid": true,
      "schematron": "Factur-X 1.09.2 (Mustang 2.26.0)",
      "pdfa": "PDF/A-3b",
      "messages": [
        {
          "part": "xml",
          "severity": "error",
          "rule": "BR-CO-25",
          "message": "string",
          "location": "string"
        }
      ],
      "truncated": true,
      "id": "6f2c7e9a-1d4b-4c3e-8a5f-2b7d9e0c1a34",
      "versions": {
        "mustang": "2.26.0",
        "verapdf": "1.30.2",
        "pdfbox": "3.0.8"
      },
      "xml_sha256": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
      "pdf_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
    },
    "display": {
      "checked": [
        "BT-1",
        "BT-109",
        "BT-110",
        "BT-112"
      ],
      "missing": []
    }
  },
  "accessibility": {
    "standard": "PDF/UA-1",
    "check": "strict",
    "conformant": true,
    "validator": "veraPDF 1.30.2",
    "rules": {
      "passed": 106,
      "failed": 0
    },
    "failures": [
      {
        "rule": "7.4.2-1",
        "code": "document-title",
        "count": 0,
        "message": "This h3 follows an h1, so a heading level is skipped. Make it an h2 and size it with CSS.",
        "elements": [
          "<h3>"
        ]
      }
    ],
    "warnings": [
      {
        "code": "filtered-text",
        "count": 0,
        "elements": [
          "string"
        ]
      }
    ],
    "truncated": true
  },
  "index": 0,
  "issues": [
    {
      "path": "items.0.data",
      "message": "string"
    }
  ],
  "field": "post.watermark.image",
  "feature": "byo_storage",
  "plan": "free",
  "limit": 0,
  "used": 0,
  "resets_at": "2024-07-29T15:51:28.071Z",
  "window_seconds": 0,
  "bytes": 0,
  "partials": [
    "string"
  ],
  "allowed": [
    "pdf"
  ],
  "output": "pdf",
  "template": "string",
  "channel": "string",
  "breaking": [
    {
      "path": "customer.email",
      "pointer": "/properties/customer/properties/email",
      "kind": "field-added-required",
      "breaking": true,
      "message": "\"customer.email\" is now required"
    }
  ],
  "safe": [
    {
      "path": "customer.email",
      "pointer": "/properties/customer/properties/email",
      "kind": "field-added-required",
      "breaking": true,
      "message": "\"customer.email\" is now required"
    }
  ],
  "current": {
    "name": "letterhead",
    "engine": "jinja2",
    "description": "string",
    "version": 3,
    "source": "string",
    "created_at": "2024-07-29T15:51:28.071Z",
    "updated_at": "2024-07-29T15:51:28.071Z"
  },
  "period_end": "2024-07-29",
  "hard_cap_units": 0,
  "render_id": "rnd_7da09ab6cd9946b798c187c2a9350852",
  "failing_items": 0,
  "page_count": 0,
  "reason": "string",
  "entry": "word/document.xml",
  "entries": 0,
  "method": 0,
  "format": "string",
  "kind": "docx",
  "value": "string",
  "name": "string",
  "content_type": "string",
  "file": "fil_5b0000000000400080000000000000a1",
  "client_id": "string",
  "role": "string",
  "request_data_retention": "off",
  "error": {
    "code": "AccessDenied",
    "http_status": 403,
    "message": "Access Denied"
  },
  "key": "string",
  "connection": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "workspace_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "provider": "s3",
    "endpoint": "string",
    "region": "string",
    "account_id": "string",
    "jurisdiction": "default",
    "bucket": "string",
    "prefix": "string",
    "force_path_style": true,
    "key_template": "string",
    "environments": [
      "live"
    ],
    "public_base_url": "string",
    "status": "active",
    "paused_reason": "failures",
    "access_key_hint": "7QX2",
    "last_tested_at": "2024-07-29T15:51:28.071Z",
    "last_error": {
      "code": "AccessDenied",
      "http_status": 403,
      "message": "Access Denied"
    },
    "created_at": "2024-07-29T15:51:28.071Z",
    "updated_at": "2024-07-29T15:51:28.071Z"
  },
  "paused_reason": "failures"
}