Troubleshooting

Common errors and how to fix them.

Grouped by where the problem usually appears - your Word template, the mapping step, the API, or the input data. Each entry follows the same format: what you see, why it happens, what to do.

Still stuck? Contact us

Word templates

Split tags, broken styling, unsupported loop or condition shapes.

Mapping & generation

Drift on re-runs, greyed-out generate button, unexpected output counts.

API responses

402, 409, 429, and 401 from automation tools.

Word templates

A placeholder I typed in Word isn’t detected.

Cause: Word silently split the run when you styled part of the tag, so the text node looks like {{client_ and name}}.

Fix: Retype the placeholder in one go without changing formatting inside the tag. Then re-upload. See the template guide for the supported placeholder styles.

My loop or condition block isn’t recognised.

Cause: A nested loop or condition is present, or the condition name doesn’t start with show_, hide_, or if_.

Fix: Flatten the loops - we support one level only. For conditions, rename the block to {#show_<thing>}. The map screen surfaces the warning above the placeholder list when this triggers.

Bold or italic styling vanished from a paragraph that has a placeholder.

Cause: Older versions used to flatten runs sharing a paragraph with a tag.

Fix: Should be fixed - if it reproduces, attach the template via /contact so we can add it to the regression set.

Mapping and generation

"Column missing" red badge on /map after applying a config.

Cause: Your data source renamed a header since the config was saved.

Fix: Open the dropdown next to the affected placeholder and pick the new column. The other mappings stay intact. The same drift surfaces on the API as HTTP 409 - see below.

Generate button is greyed out.

Cause: At least one required placeholder is unmapped, or the document is grouped but no parent ID is set.

Fix: Scroll through the mapping list - any placeholder with no column selected blocks the button. Pick a column or remove the placeholder from the template.

API responses

HTTP 402 - usage_limit_reached

Cause: You hit the monthly document allowance for your plan.

Fix: Upgrade (see limits doc), wait for the UTC monthly reset, or - on a shared license - ask the owner to upgrade. Single-row downloads count toward the cap too.

HTTP 402
{
  "code": "usage_limit_reached",
  "plan": "free",
  "used": 10,
  "limit": 10,
  "requested": 3
}

HTTP 409 - drift

Cause: The JSON keys you POSTed (or columns in the Excel) don’t match the config’s expected columns.

Fix: Fetch the expected columns first via GET /api/v1/configs/<id> and align your payload. The response includes suggestions when a similar name exists.

HTTP 409
{
  "error": "drift",
  "missingColumns": ["client_name"],
  "suggestions": { "client_name": ["customer_name"] }
}

HTTP 429 - rate limited

Cause: You’re sending more than 60 run requests per minute.

Fix: Back off and retry with an exponential delay. Send an Idempotency-Key so retries don’t double-bill if you cross the limit mid-flight.

HTTP 401 when fetching downloadUrl from Zapier / Make / n8n.

Cause: The "upload from URL" or "download file" action didn’t send your Bearer token. doctagd outputs are private.

Fix: Use the HTTP / Webhooks module with method GET and an Authorization: Bearer dtgd_… header. See the per-platform steps in the API docs.

Input data

"File too large" or payload-too-large error.

Cause: A single output exceeded 8 MB, the zip exceeded 80 MB, or a JSON body exceeded 512 KB.

Fix: Reduce embedded image sizes in the Word template, split the Excel into smaller batches (≤500 rows), and trim oversized free-text cells (≤10,000 characters).

Grouped output produced fewer documents than I expected.

Cause: You applied the grouping suggestion - that’s by design. Output is one document per parent ID, not per row.

Fix: Remove the grouping suggestion on /confirm to revert to one document per row.

Bullet rendering caught a column I didn’t want.

Cause: Heuristics flagged the column as multi-value - usually because most cells contain commas.

Fix: Dismiss the suggestion card on /confirm or /map. Future runs of the same config won’t re-apply it.

When all else fails

Send us the template plus an Excel that reproduces the issue via the contact form. We add real-world reproducers to the regression set, so anything you report becomes a fixture against future regressions.