Articles on: API Reference

"API Errors and Render Timing: 403, 404, 500, Out of Credits and Async URLs"

This article lists the errors the Templated API returns, what they mean, and how to fix them. It also explains render timing and storage.

All errors are returned as JSON with an error field:

{ "error": "API quota exceeded. Upgrade your plan to generate more renders." }

Authentication errors

Status	Message	What to do
401	`Not authorized`	The `Authorization` header is missing or does not start with `Bearer` . Use `Authorization: Bearer YOUR_API_KEY`.
404	`API key not valid. Please check your Authorization header.`	The key is wrong or was regenerated. Copy it again from the API Key page: https://app.templated.io/api-key

Note: an invalid API key returns 404, not 401. If you get 404 on every request, check your key first.

Account and credit errors (403)

Message	Meaning
`API quota exceeded. Upgrade your plan to generate more renders.`	You have used all the credits of your plan for this period.
`Insufficient credits. This render requires X credits, but you only have Y remaining.`	The request needs more credits than you have left. This happens with multi-page templates (1 credit per page) and videos.
`Your payment method on file is past due...`	Your last payment failed. Update your card in Account Settings > Manage Subscription.
`Your account is blocked. Please contact support.`	Contact support@templated.io.
`Your API access has been suspended...`	Contact support@templated.io.
`You're not authorized for generate renders for this template`	The template belongs to another account or team. Use a template from the account that owns the API key.
`HTML output format is only available on Enterprise plans.`	`format: "html"` requires the Enterprise plan.

Out of credits

Renders that fail because you are out of credits are not queued. After you upgrade, send them again.
Upgrading applies the new credit limit immediately: https://app.templated.io/upgrade
In the editor, a download with no credits left can stay stuck on "Downloading". Upgrade and try again.
In Zapier, an authentication error such as "Cannot refresh authentication" can also be caused by running out of credits.

Request errors (400)

Message	Fix
`No template specified.`	Add `"template": "TEMPLATE_ID"` to the body.
`Invalid format '...'. Supported formats: ...`	Use `jpg`, `png`, `webp`, `pdf` or `mp4` (or `html` on Enterprise).
`Scale parameter must be between ...`	Use a `scale` value inside the allowed range.
`merge and zip cannot both be true...`	Choose one: `merge` for a single PDF, or `zip` for a ZIP of files.
`webhook_url is required when combining merge=true with async=true...`	Add a `webhook_url`, or remove `async`. Same for `zip`.

Not found (404)

Template not found: TEMPLATE_ID: check the template ID (see "Where to find your template ID"). Template IDs are different from render IDs.

Server errors (500)

An unexpected error occurred while generating your render.

The most common cause is a very large source image. The renderer loads every image in memory. A huge file (for example 20000 x 20000 px) can crash the render.

How to fix:

Resize images before sending them. Keep the longest side under about 4000 px, or about 2 times the size of the layer it goes into.
Make sure the image URL is public and returns the image directly (not an HTML page).
Retry once. If it keeps failing, send the payload to support (see below).

403 AccessDenied when opening the render URL (async renders)

With "async": true, the API answers immediately, before the file exists. If you open the returned url right away you may see an AccessDenied (403) XML page. The file is simply not ready yet.

Choose one of these options:

Use synchronous rendering (the default, without async). The URL works as soon as the API responds.
Use a webhook_url. When the render finishes, Templated sends a POST with success, render_id, status and the final url.
Poll the render with GET https://api.templated.io/v1/render/{renderId} until status is COMPLETED, then use the url from that response.

Use the URL from the webhook or from the GET response. It is the final file location.

How long does a render take?

Images and PDFs: usually around 2 to 3 seconds.
Multi-page templates, large images and many fonts take longer.
Videos (mp4) take longer depending on duration, size and frames per second. Use async with a webhook for videos.

If renders are much slower than usual or failing for everyone, check the status page: https://status.templated.io

How long are renders stored?

Render files are stored with no storage limit and you can link to the render URL directly. Opening or downloading an existing render URL does not use credits.

Send this when you contact support

Ask in the chat and include:

The render ID or the full request body (without your API key).
The template ID.
The exact error message and status code.
The time of the request.

FAQ

Q: Why do I get 404 "API key not valid"?
A: The key is wrong or was regenerated. Copy it again from the API Key page in the dashboard and send it as Authorization: Bearer YOUR_API_KEY.

Q: What does "API quota exceeded" mean?
A: You have no credits left for this period. Upgrade your plan to continue. Failed requests are not queued; send them again after upgrading.

Q: Why does my render URL show AccessDenied?
A: You used async rendering and opened the URL before the file was ready. Wait for the webhook or poll GET /v1/render/{id} until the status is COMPLETED.

Q: Why do I get a 500 error?
A: Most often a source image is too large. Resize it to under about 4000 px on the longest side and try again.

Q: How long does a render take?
A: Usually 2 to 3 seconds for images and PDFs. Videos take longer.

Q: Is the API down?
A: Check https://status.templated.io

Q: Do renders expire?
A: No. Renders are stored and you can keep linking to the URL.

Updated on: 01/10/2026

Was this article helpful?

Thank you!