Errors

Errors are returned as problem details (RFC 9457) with the content type application/problem+json. Every error carries a stable machine-readable code; branch on that, never on the human-readable title or detail.

{
  "type": "https://docs.dynamicdocumentapi.com/errors/template_runtime_error",
  "title": "Template runtime error",
  "status": 422,
  "code": "template_runtime_error",
  "detail": "'dict object' has no attribute 'total' (line 12, column 7)",
  "errors": [
    { "path": "/data/items/0/qty", "code": "type_error", "message": "expected number" }
  ],
  "render_id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q",
  "request_id": "req_01J9ZM4T6W8Y0A2C4E6G8J0K2M",
  "doc_url": "https://docs.dynamicdocumentapi.com/errors/template_runtime_error"
}

Failed renders carry the same information. A sync render that fails returns 422 with the render error, and an async render ends with status: "failed" and an error object holding code, message and, for template problems, line, column and excerpt.

Handling errors

Retry these:

• 429 after the number of seconds in Retry-After
• 500 and 503, with exponential backoff; 503 also sends Retry-After
• 409 idempotency_in_progress, after a short pause, with the same idempotency key

Don't retry the others without changing the request: 400, 401, 402, 403, 404, 410, 413, 415, 422 and 423 describe something that will fail the same way again.

Always send an Idempotency-Key header so that a retry can never produce a second document, and log request_id next to your own identifiers.

const MAX_ATTEMPTS = 5;

async function createRender(body: unknown, idempotencyKey: string) {
  for (let attempt = 1; ; attempt++) {
    const response = await fetch("https://api-eu.dynamicdocumentapi.com/v1/renders", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.DYNAMIC_DOCUMENT_API_KEY}`,
        "Content-Type": "application/json",
        "Idempotency-Key": idempotencyKey,
      },
      body: JSON.stringify(body),
    });
    if (response.ok) return response.json();

    const problem = await response.json().catch(() => ({}));
    const retryable =
      response.status === 429 || response.status >= 500 || problem.code === "idempotency_in_progress";
    if (!retryable || attempt === MAX_ATTEMPTS) {
      throw new Error(`${problem.code ?? response.status}: ${problem.detail ?? ""} (request ${problem.request_id ?? "?"})`);
    }

    const retryAfter = Number(response.headers.get("Retry-After"));
    const delaySeconds = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, delaySeconds * 1000));
  }
}

400 Bad Request

401 Unauthorized

402 Payment Required

403 Forbidden

404 Not Found

408 Request Timeout

409 Conflict

410 Gone

413 Payload Too Large

415 Unsupported Media Type

422 Unprocessable Entity

Most render failures land here. When a render was created before it failed, the body includes render_id.

invalid_pdf_source and pdf_password_required come from the PDF tools, and scene_invalid and data_invalid from canvas templates. The last four codes come from PDF/UA, PDF/A and e-invoice output: such renders fail without being billed and carry the validation report in result.

423 Locked

429 Too Many Requests

500 and 503

A render that the platform loses fails with the code render_lost: its job expired in the queue, or it stopped without a result well past its time limit. Nothing is billed; render it again.

Render warnings

Warnings don't fail a render. They appear in the render object's warnings array and in webhook payloads, and they are worth logging: they usually explain why output doesn't look the way you expect.

Email sends report their own error codes in the email send object; see Email delivery.