Error handling
Integration endpoints return standard HTTP status codes. JSON error bodies use:
{ "error": "Human-readable message" }Validation errors may include code and details:
{
"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:
{
"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:
{
"error": "callbackUrl must use HTTPS",
"code": "validation_failed",
"details": {
"field": "callbackUrl",
"reason": "https_required"
}
}reason | Typical field | Meaning |
|---|---|---|
https_required | callbackUrl | Use https:// (not http://). See Async batch rendering — Completion callback for delivery and retries. |
required | e.g. templateId, outputIds | Field is missing or empty |
invalid_format | e.g. templateId, processBatchId | Value is not a valid UUID |
invalid_value | e.g. deliveryChannel | Value is not in the allowed set |
invalid_json | (omitted) | Request body is not valid JSON |
Status codes
| Code | Meaning | What to do |
|---|---|---|
400 | Invalid JSON, bad parameters, or missing required variables | When code is validation_failed, check details.missingFields, or details.field + details.reason |
401 | Missing or invalid API key | Verify key header and that the key is not revoked |
403 | JWT supplied or missing permission | Use X-Api-Key with render.execute |
404 | Template 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 |
409 | Integration 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) |
422 | Template not approved, or batch expectedDocumentCount mismatch / would exceed planned total | Approve the template; align or omit expectedDocumentCount on follow-up chunk POSTs |
429 | Render quota exceeded | Retry later or contact support |
500 | Server error | Retry with backoff; include X-Request-ID when reporting issues |
Response header
All responses include X-Request-ID for support and log correlation.