validation_error

HTTP 422. The request was well-formed and the template exists, but data does not match that template version’s JSON Schema. Nothing was rendered and nothing was billed.

422 Unprocessable Entity

{
  "error": {
    "type": "validation_error",
    "message": "The data payload does not match the template schema.",
    "docs_url": "https://galleyrender.com/docs/errors/validation_error",
    "errors": [
      {
        "path": "data.issued_on",
        "message": "data.issued_on is required",
        "expected": "string (required)",
        "received": "missing",
        "example": "2026-09-16"
      },
      {
        "path": "data.line_items[1].quantity",
        "message": "data.line_items[1].quantity must be number",
        "expected": "number",
        "received": "string",
        "example": 2
      }
    ]
  }
}

Why this happens

There is one raise site: the schema check that runs on POST /v1/render, for every render and every batch item, before any work starts. It fires when a required property is missing, a type is wrong, a format such as email or date does not match, a value falls outside minimum/maximum/minLength, an enum is not honoured, an array is shorter than minItems, or the schema sets additionalProperties: false and you sent an extra key.

Types are never coerced: "2" is not 2, and "true" is not true.

How to fix it

Repair the payload mechanically. For each entry, set the value at path to something matching expected, using example as the model. If the shape is unclear, read the schema with GET /v1/templates/:ref.

Before a large batch — or any payload assembled from a source you do not control — dry-run it with POST /v1/templates/:ref/validate. It returns these same entries, renders nothing and costs nothing.

Does retrying help?

Only after you change the payload. An identical retry produces an identical 422.