Skip to main content

Troubleshooting and FAQ

Most problems with personalised images come down to three things: a cached copy, an email client that blocks or proxies images, or an account that has run out of credit. Find your symptom below. If you are still stuck, contact support and include the image URL and the time you saw the problem.

Images not showing or not updating​

1. My image is not updating after I edited the design​

Email clients, browsers and proxies keep a copy of each image URL for a while. OKZest tells caches to keep an image for up to 30 minutes, so an old URL can keep showing the old image for that long. Wait, or add a throwaway parameter to the image URL, for example &v=2 (any change to the query string creates a new cache entry). Open the image URL in a private window to see what we are serving now. Docs: Merge tags and URL parameters, Share page

2. Why does the same image URL show different results in different places?​

Each place that cached the URL (your browser, Gmail's proxy, your ESP's preview) keeps its own copy and refreshes it on its own schedule. Changing the URL, for example with a version parameter (a name that is not one of your merge-tag names) or a different merge-tag value, forces a fresh copy everywhere. Docs: Merge tags and URL parameters

3. How do I force a fresh image?​

Add or change a query parameter on the image URL (&v=20261112, or a message id). Use a name that is not one of your merge-tag names, because merge tags are read from the URL as parameters. The renderer ignores parameters it does not use, so this is safe on a normal design. Personalised images already refresh on their own when a merge-tag value changes the URL. There is no purge button or purge API. Docs: Merge tags and URL parameters

4. My image is a tiny blank picture​

This usually means one of three things.

  1. The c (company) or i (design) value in the URL is mistyped or the design was deleted. A bad id returns a blank image, not an error, and that blank can be cached for up to 30 minutes.
  2. You are on the Free plan and have used all your credit.
  3. A rendering problem happened on our side. Reload after a few minutes.

Check the URL against the one on the Share page, then check your usage in the dashboard. Docs: Share page, Pricing, Billing and usage

5. My image shows default text instead of the recipient's details​

Check the merge tag in your ESP matches the tag in the URL exactly and that the contact has a value. Where your account is on a paid plan, has reached its plan limit and cannot top up, images render with each field's default text instead of the personalised values. Your dashboard shows live usage; Pricing explains limits and auto top-up. Docs: Merge tags, Pricing

6. The image has a "Made with OKZest" badge​

Badges appear on free-plan images while free credit remains. A paid credit or paid plan removes them. Previews inside the editor never use credit, but on the Free plan a preview may still show the badge. Docs: Pricing

7. My background image from a URL does not change when the source changes​

Background images fetched from your own URL may be reused. Change the source URL (for example add a version parameter to it) to fetch a new copy. Docs: Edit page

Email clients​

8. The image does not show in Outlook​

Outlook on the desktop blocks external images until the reader chooses to download pictures. This is Outlook's setting, not an error from OKZest. Add alt text and set width and height on the image tag, and consider asking readers to add you to their safe senders. Docs: Share page

9. Gmail still shows the old image​

Gmail loads images through its own proxy and may keep its own copy. Use a different image URL for each send, with a version parameter or differing merge-tag values, so Gmail treats it as a new image. Docs: Merge tags and URL parameters

10. My open counts look too high, or opens appear before anyone read the email​

Apple Mail Privacy Protection and some proxies preload images when mail arrives, so a view can be recorded before a person reads it. The OKZest FAQ says billing counts image requests, not sends, and that counts can differ from reported opens for this reason. Docs: Billing and usage

11. Which image format should I use in email?​

Use JPG or PNG. WebP and PDF are not supported by every email client. For the API, the default is JPG unless the design has a transparent canvas. Docs: Images API

12. Will it work with my email tool?​

Anything that accepts an HTML image tag and lets you insert a dynamic URL or merge tag should work. The OKZest FAQ lists the providers we have tested, or ask support to check yours. Docs: Zapier, AI assistants (MCP)

API errors​

13. I get 401 Unauthorized​

The x-api-key header is missing, empty, wrong or revoked. Send the key in x-api-key, not in an Authorization header. Call GET /v1/whoami: a 200 proves the key works. If it fails, create a new key in the dashboard. Docs: API introduction, Who am I endpoint

14. I get 400 "Design not found"​

The design_id does not exist in the key's account, or the key's user cannot view the design's project. We return the same message for both so ids from other accounts are not revealed. List valid ids with GET /v1/images and use a key from the owning account. Docs: Images API, Designs API

15. I get 400 "Unsupported format"​

The message lists the valid formats. Use one of them (jpeg is accepted as jpg). Docs: Images API

16. My layer change is ignored, or the call fails after I edit a layer​

Check the layer ids with GET /v1/images/{id}/fields and that any image URL you pass is public and starts with http or https. Docs: Designs API, Edit page

17. My API call returns 200 but the image is blank or tiny​

There is no "out of credits" error status. When an account is out of credit the call can succeed and return a 1x1 transparent image. Check your usage in the dashboard, then add credit or change plan. Docs: Pricing, Images API

18. I get an error saying "Request failed", or a 500​

This can come back as a 400 or a 500. Retry once. If it keeps failing, retry with increasing waits, then contact support with the time of the request and the design id. Docs: API introduction, Feedback and support

Limits and 429​

19. Do I get 429 Too Many Requests from the API?​

The REST API (/v1) has no rate limiter of its own in our code. Rate limits apply to the MCP endpoint. A 429 can also come from the okzest.com website itself (dashboard or sign-in pages) or from something in front of it, such as your own network. We do not state numbers here. Limits can change, so check the error message you receive and the MCP server page. Docs: API introduction

20. My AI tool (MCP) says "Rate limit reached"​

The MCP connector limits requests per minute for each account, and limits tool calls that render images more tightly. The render-limit error message states the current limit. Wait one minute, then retry. A 429 from the MCP endpoint does not include a Retry-After header, so do not wait for one. Reuse existing design ids and image URLs rather than regenerating. Docs: MCP server

21. How should my code handle a 429 or 5xx?​

Stop, wait at least a minute for a 429, then retry with exponential backoff and random jitter. Cap the number of retries. Docs: API introduction

Account and credits​

22. What counts as an image view or credit, and how do I see my usage?​

Billing counts image requests from email apps, not sends. Copies served from a cache are not counted again. The dashboard shows your live usage. Allowances and prices are on the plans page. Docs: Billing and usage, Pricing

Still stuck?​

Email support from the Support page and include: the image URL, the design name, what you expected, what you saw, and the time.

Still stuck?​

Message us from the Feedback and support page and include the image URL, the design name, what you expected, what you saw, and the time.