data_validation_error

HTTP 422 · code: "data_validation_error" · type: https://docs.formfeed.dev/errors/data-validation

The render asked for validate_data: true, and its data does not match the data schema stored with the template version. Formfeed checks the data only when a render or batch item asks for it with validate_data: true; without it, the data is not checked against the schema at all.

The check runs before anything is rendered, recorded or counted, so the failed request costs nothing. errors lists every place where the data does not match, each with path and message; detail repeats the first and says how many more there are. In a batch, detail starts with the item (Item 3: …), index names it, failing_items says how many items of the same template version failed, and nothing is queued.

Example

{
  "type": "https://docs.formfeed.dev/errors/data-validation",
  "title": "Data validation failed",
  "status": 422,
  "detail": "data.invoice.number: must be string (and 1 more)",
  "code": "data_validation_error",
  "errors": [
    {
      "path": "data.invoice.number",
      "message": "data.invoice.number: must be string"
    },
    {
      "path": "data.invoice.lines[0].qty",
      "message": "data.invoice.lines[0].qty: is required"
    }
  ],
  "request_id": "req_4b7c1e9a2f3d4c5b8a6e7f9012"
}

Common causes

• A required field is missing, or a field has the wrong type.
• A value is not one of the values an enum allows (must be one of "draft", "sent").
• A field the schema does not allow, where it sets additionalProperties: false (is not allowed by the schema).
• The data was built for an older version of the template, and the published version's schema changed.

How to fix it

• Fix the fields errors names. Paths start at data, so data.invoice.lines[0].qty is qty in the first line.
• Compare your data with GET /v1/templates/{id}/schema, or check it without rendering with POST /v1/templates/{id}/validate.
• Generate types from the schema with formfeed types, so your code cannot send data of the wrong shape. See Typed template data.

A request with validate_data: true for a template version without a stored schema, or for html or a url, is refused with invalid_request instead.

Retry?

No. The same request gets the same answer. Fix the data, then send the request again with a new Idempotency-Key or without one: a 4xx answer is stored under its key for 24 hours, so the old key returns this problem again. See retrying.