Error handling

Integration endpoints return standard HTTP status codes. JSON error bodies use:

json
{ "error": "Human-readable message" }

Validation errors may include code and details:

json
{
  "error": "validation failed",
  "code": "validation_failed",
  "details": {}
}

Required variables

Templates can mark sample-data fields as Required in the admin app. On render, the platform validates your variables against that field set before producing HTML or PDF.

When required values are missing, the API returns 400 with:

json
{
  "error": "Required variables are missing",
  "code": "validation_failed",
  "details": {
    "missingFields": ["firstName", "policies.0.endDate"]
  }
}

missingFields lists dot paths for each unsatisfied field. Collection paths use zero-based indices (for example policies.0.endDate).

Check error.details.missingFields in your integration to show a clear message or retry after fixing input data.

Field validation (details.field / details.reason)

For other 400 responses with code: validation_failed, read details.field and details.reason:

json
{
  "error": "callbackUrl must use HTTPS",
  "code": "validation_failed",
  "details": {
    "field": "callbackUrl",
    "reason": "https_required"
  }
}
reasonTypical fieldMeaning
https_requiredcallbackUrlUse https:// (not http://). See Async batch rendering — Completion callback for delivery and retries.
requirede.g. templateId, outputIdsField is missing or empty
invalid_formate.g. templateId, processBatchIdValue is not a valid UUID
invalid_valuee.g. deliveryChannelValue is not in the allowed set
invalid_json(omitted)Request body is not valid JSON

Status codes

CodeMeaningWhat to do
400Invalid JSON, bad parameters, or missing required variablesWhen code is validation_failed, check details.missingFields, or details.field + details.reason
401Missing or invalid API keyVerify key header and that the key is not revoked
403JWT supplied or missing permissionUse X-Api-Key with render.execute
404Template not found in your org, or integration process not found (list/download)Confirm templateId is a template UUID, not a version UUID; for batch list/download, confirm processBatchId from a prior 202 for your org
409Integration process is not open (batch submit)Start a new process (omit processBatchId or use a new client UUID) — the process closed after completion rules (planned total or idle grace)
422Template not approved, or batch expectedDocumentCount mismatch / would exceed planned totalApprove the template; align or omit expectedDocumentCount on follow-up chunk POSTs
429Render quota exceededRetry later or contact support
500Server errorRetry with backoff; include X-Request-ID when reporting issues

Response header

All responses include X-Request-ID for support and log correlation.