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 → Design tab → set Quiet Zone 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 tab. 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.

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 disabled

Cause: Either no template is open, or the template has not been saved yet.

Fix: Make sure a template is open in the Designer and click Save (or press ⌘S) before generating.

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 Generate Preview again, 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, 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 → Design tab → toggle Use as variable to ON, configure a name in the Variable tab, and save the template. See Creating a Variable.

My default value doesn’t appear on the canvas

Cause: The Use as variable toggle may be OFF for that element, so it’s not reading the default from the Variable tab.

Fix: Toggle Use as variable ON, then set the default in the Variable tab.

Account & Billing

Check your spam/junk folder. The magic link expires in 15 minutes — if it has expired, go to the login page and click Resend link.

I can’t invite team members

Cause: Invitations require the Team plan and Admin or Owner role.

Fix: Upgrade to the Team plan via Settings → Billing → Change plan. See Choosing a Plan.

My API renders are returning 429 errors

Cause: You’ve reached your monthly API quota.

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.