Troubleshooting & FAQ

Designer

My QR code won’t scan

Most likely cause: The quiet zone (margin) is too small, especially on printed material.

Fix: Select the QR element → Appearance section of the Properties panel → set Quiet Zone (Margin) to at least 4 modules, or click Print Safe (4 modules).

Also check that there is sufficient contrast between Dark Color and Light Color — avoid light-on-light or dark-on-dark combinations.

Text is cut off or shows ”…”

Cause: The text is longer than the element’s bounding box and the overflow mode is set to Clip or Ellipsis.

Fix: Select the text element → Typography section of the Properties panel. Either:

Increase the element size (drag a corner handle).
Enable Auto-Fit Text so the font shrinks to fit.
Change Overflow to Visible to allow text to overflow the box.

My template says “Read only”

Cause: You’re viewing a shared template that belongs to another user. Only its creator can edit it; you can still generate images from it.

Fix: Click Use this template in the header. This creates your own editable copy in a project you own. See Reusing & Copying Templates.

I accidentally deleted an element

Fix: Press ⌘Z / Ctrl+Z to undo. Zandovi keeps up to 50 history steps. See Undo, Redo & History.

I can’t select an element on the canvas

Cause: The element may be locked.

Fix: Open the Layers panel (left sidebar) and click the lock icon on that layer row to unlock it, then select it on the canvas.

The Generate button is missing or disabled

Cause: The Generate button only appears while a template is open in a tab (not on the project overview or list), and it’s disabled for a moment while that template loads. An unsaved template can still render on the Single Image tab, but the API button and the Batch from CSV tab need a saved template.

Fix: Open a template and wait for it to load. For batches or the API example, save the template first (⌘S).

Cause: The link expired. Every link is created with a fixed lifetime set by your plan, and when it lapses the image is deleted.

Fix: Generate the image again and share the new result. Expired links can’t be extended. Check the expiry shown in the Shared Links tab before sending a link somewhere long-lived. See Public Share Links.

I revoked a link but it still loads

Cause: Shared images are cached at the edge for up to five minutes. Revoking purges that cache, but a copy can still be served briefly.

Fix: Wait a few minutes and check again. If it’s still resolving after that, the revoke may have failed — try revoking again from the Shared Links tab.

Cause: Either your plan doesn’t include share links, or the output size exceeds your plan’s limit. Hover the button for the specific reason.

Fix: Lower the scale or DPI if it’s a size limit, or see Choosing a Plan.

Cause: Each plan caps how many links can be live at once, and you’re at the cap.

Fix: Revoke a link you no longer need in the Shared Links tab, or upgrade. Expired links stop counting automatically.

”This image can no longer be shared”

Cause: The preview on screen came from a render that’s too old to publish. Zandovi only publishes bytes it can verify it rendered recently.

Fix: Click Regenerate, then Share the new result.

Cause: Members only see the links they created themselves.

Fix: Ask the person who created it to copy or revoke it. Workspace Owners and Admins can see and revoke every link in the workspace.

Variables & Batch

My batch job shows validation errors

Cause: One or more CSV rows have missing required values, a value that isn’t on a variable’s allowed list, an image reference that doesn’t exist or isn’t yours, or a barcode column contains data in the wrong format for the selected barcode type.

Fix: Read the flagged rows listed under the upload area, correct them in your spreadsheet, re-upload, and re-submit. For a job that already ran, expand it in Job History — the first five failed rows and their reasons are shown there, with a count of any beyond that.

My API batch submission returned 409

Cause: Either the Idempotency-Key was already used for a different submission (BATCH_IDEMPOTENCY_KEY_REUSED), or you called the result endpoint before the job finished (BATCH_RESULT_NOT_READY).

Fix: Use a fresh key for each new batch (reuse a key only when retrying the same one), and poll GET /api/v1/batch-jobs/{jobId} until status is COMPLETED before fetching the result. See Batch Rendering.

My batch result download URL stopped working

Cause: Result download URLs are valid for 1 hour.

Fix: Call GET /api/v1/batch-jobs/{jobId}/result again for a fresh URL — no re-render needed. If it returns 404 BATCH_RESULT_NOT_FOUND, the job (and its archive) was deleted; if it returns 410 BATCH_RESULT_EXPIRED, the archive passed its 30-day retention window and the job has to be re-run.

My batch results are gone but the job still shows COMPLETED

Cause: Result archives are kept for 30 days from completion, then deleted. Expiry takes only the ZIP — the job, its counters, and its per-row outcomes stay readable, which is why the job still lists as COMPLETED.

Fix: Re-run the batch if you need the images again. To avoid this, copy the ZIP into your own storage when the job finishes rather than treating Zandovi as long-term storage. See Result retention.

My completion callback never arrived

Cause: Delivery is retried 5 times over roughly 15 minutes and then given up on. Common reasons an endpoint refuses every attempt: it isn’t https, its hostname doesn’t resolve publicly, it answers a redirect (redirects are never followed), it takes longer than 10 seconds to respond, or it returns a non-2xx status.

Fix: Read completionCallback on GET /api/v1/batch-jobs/{jobId} — status, attempts, and lastError say exactly what happened. Return 2xx as soon as you’ve stored the payload and do the real work afterwards. See Completion Callbacks.

My callback signature never verifies

Cause: Almost always the body was parsed before it was verified. The signature covers the exact raw bytes we sent, so re-serializing the parsed object changes key order or whitespace and the HMAC no longer matches.

Fix: Capture the raw request body on that route, compute HMAC-SHA256(secret, "<t>.<rawBody>"), and compare it against any v1 value in the X-Zandovi-Signature header. The secret is in the app under Settings → API Keys. See Verifying the signature.

Variable inputs don’t appear in the Generate dialog

Cause: The template has no variable-bound elements.

Fix: Select an element → Variable section at the top of the Properties panel → turn on Variable (text) or Use as variable (image, QR code, barcode) and give it a name. See Creating a Variable.

My default value doesn’t appear on the canvas

Cause: The element’s variable switch may be off, so the element isn’t a variable and its Default field doesn’t apply.

Fix: Turn the switch on in the Variable section, then set the default: a text variable’s default is its Text Content; QR codes, barcodes and images have a Default / Default URL field in the Variable section.

Account & Billing

Check your spam/junk folder. The sign-in link expires in 15 minutes (a sign-up link in 24 hours) — if it has expired, go to the login page and request a new one.

Cause: An email security scanner opened the link before you did. Some company mail systems open every link in a message automatically, which used up the single-use link.

Fix: Request a new link from the login page. Since this release, the link opens a page with a confirmation button that scanners don’t press, so they can no longer use it up. If it keeps happening, contact support.

I can’t invite team members

Cause: Invitations require a team workspace on a multi-seat plan (Studio, Team or Business) and the Admin or Owner role.

Fix: Ask the workspace Owner to upgrade via Settings → Billing → Change plan. See Choosing a Plan.

My API renders are returning 429 errors

Cause: You’ve reached your monthly API quota (CSV batches from the Designer draw from it too).

Fix: Wait for the quota to reset (check Settings → Billing for reset date), or upgrade to a plan with a higher quota. See Usage & Quotas.

I deleted an API key and now my integration is broken

Deleted keys stop working immediately and cannot be recovered. Create a new key in Settings → API Keys, update your integration with the new key, and store it securely. See API Keys.

Still stuck?

If you can’t find an answer here, reach out via the support channel linked in your account or email the address on the Zandovi website.