Errors

Every error is JSON with a code, a message in plain English, the field it is about and a request id. The code stays the same, so let your program test the code. The words of the message can change.

The error format

HTTP/1.1 400 Bad RequestContent-Type: application/jsonMR-Request-Id: req_AW2J9HmisYTi {  "error": {    "code": "invalid_param",    "message": "must be a hex colour like #0f172a, or transparent",    "field": "data.title.color",    "request_id": "req_AW2J9HmisYTi"  }}

Field	About
`code`	A short, stable name for the problem. The tables below list every code.
`message`	What is wrong, in plain English, for a person to read. The words can change.
`field`	The field, header or query parameter the error is about. Not every error has one.
`request_id`	The id of this request. Every answer, error or not, has the same id in the `MR-Request-Id` header. Send it to support.

The field path

The path uses dots for object keys and brackets for list items:

Path	Means
`data.title.color`	The `color` in the object you sent for the param `title`.
`data.page2.title`	The value of `page2.title` in `data`.
`sizes[1]`	The second item of `sizes`.
`rows[41]`	The 42nd row of a batch.
`scene.pages[0].layers[2].font`	The font of the third layer on the first page of a scene you sent.
`Idempotency-Key`	A header.

HTTP statuses

Status	Means	Try again?
400	The request is not valid. field names the problem.	No. Change the request.
401	No key, or the key is not valid.	No. Send a valid key.
402	No credits left, or a plan limit (templates, members, stored files) is reached.	No. Turn on overage, upgrade, delete files, or wait until new credits come.
403	Not allowed: a bad link signature, an Origin the MCP server does not allow, a missing Turnstile check.	No.
404	The template, render, batch, asset or route does not exist in this workspace.	No.
405	The method is not allowed on this path.	No.
409	Conflict: the template is not published, a job is no longer queued, an asset is in use, or a request with the same Idempotency-Key is still running.	Only in_progress and conflict: try again in a moment.
413	The body or the file is too large.	No. Send less.
422	The request cannot be done: an Idempotency-Key with a different body, or the AI made no valid template.	ai_invalid: change the description and try again.
429	Too many requests, too many running jobs, or the monthly AI limit.	Yes, after the Retry-After header (seconds). ai_limit: next month.
451	The workspace is frozen, or a reviewer workspace has ended.	No. Write to support.
500	Something went wrong on our side, or the render failed.	Yes.
502	A service we use failed.	Yes.
503	Not available now: a set-up step is missing, or the daily AI limit is reached.	ai_busy: after 00:00 UTC.
504	A service we use took too long.	Yes.

For 429 and for 409 in_progress, wait for the number of seconds in the Retry-After header. For 500, 502 and 504, wait a few seconds and try again, at most a few times. Send an Idempotency-Key so a retry never charges twice.

Error codes

Status	Code	When
400	`invalid_request`	The body is not JSON, a field has the wrong type, a required field is missing, or the request breaks a rule of the route (for example two CSV sources in a batch).
400	`invalid_param`	A value is not valid: a value in data, a size name, metadata over 4 KB, ?inline=1 with more than one size, or a webhook URL we do not call.
400	`unknown_param`	A key in data matches no changeable layer. Send ignore_unknown: true to skip such keys.
400	`invalid_scene`	A template scene breaks a rule. field names the place, like scene.pages[0].layers[2].font.
400	`reserved_for_video`	A scene uses a field kept for video (duration, fps, keyframes and others).
400	`invalid_template`	A stored template version no longer passes the checks. Publish a corrected version.
400	`limit`	The output is over the pixel limit, the images are over the input pixel limit, the render uses more than 20 different image URLs, or it needs too much memory. The message says which.
400	`too_many_pages`	A signed link would make a PDF of more than 10 pages.
400	`unknown_size`	POST /v1/links got a size the published version does not have.
400	`invalid_size`	POST /v1/templates/generate got a size that is not WIDTHxHEIGHT.
400	`invalid_csv`	The CSV cannot be read. The message gives the line.
400	`url_refused`	We do not fetch this URL: a private address, a wrong port, too many redirects, too large, or no answer in time.
400	`url_failed`	The URL answered with a status that is not 2xx.
400	`unsupported_type`	The file is not a PNG, JPEG, GIF, WebP or SVG image or a UTF-8 CSV. An image URL in data cannot be an SVG.
400	`invalid_svg`	The SVG cannot be read, or it has no size (set width and height, or a viewBox).
400	`image_too_large`	The image is over 16 megapixels.
401	`unauthorized`	No key, or the key is not valid.
401	`invalid_token`	An MCP OAuth access token is not valid or has expired.
402	`no_credits`	The render needs more credits than are left, and overage is off or at its cap.
402	`plan_limit`	The plan's template, member or stored-file limit is reached, or overage on the Free plan.
403	`unsigned`	A signed link has no s.
403	`bad_signature`	A signed link's signature does not match.
403	`origin`	A browser Origin that the MCP server does not allow.
403	`turnstile`	POST /v1/preview without a key needs a Turnstile token from our pages.
404	`not_found`	No such template, version, render, batch, asset, webhook, delivery or route.
405	`method_not_allowed`	Signed links answer GET and HEAD only; /mcp answers POST only.
409	`not_published`	The template has no published version. Publish it first.
409	`not_queued`	DELETE /v1/renders/{id} on a job that has started or ended.
409	`in_use`	DELETE /v1/assets/{id} on an asset that a version of a template uses.
409	`conflict`	Two publishes of one template at the same moment. Try again.
409	`in_progress`	A request with the same Idempotency-Key is still running. Retry-After: 2.
413	`too_large`	The body or the file is over its limit. The message gives the limit.
422	`idempotency_mismatch`	The Idempotency-Key was used with a different body in the last 24 hours.
422	`ai_invalid`	The AI could not make a valid template from the description.
429	`rate_limited`	Too many calls this minute, or too many running jobs. See Retry-After.
429	`busy`	Too many renders of one workspace at the same moment. Retry-After: 1.
429	`ai_limit`	This month's AI templates for the plan are used.
451	`frozen`	The workspace is frozen.
451	`expired`	A reviewer workspace has ended.
500	`internal`	Something went wrong on our side. Try again.
500	`render_failed`	The render failed. Try again.
502	`ai_failed`	The AI service could not answer.
503	`ai_busy`	The AI template maker has done today's work for the whole service.
503	`not_configured`	A part (signed links, webhooks, the AI) is not set up on this server.
504	`ai_timeout`	The AI took too long.

The account pages in the editor (plan, members, keys) have some codes of their own, for example payment_failed when the payment for a plan change does not go through. The page shows their message.

Errors of jobs

A job or a batch row that fails has "status": "failed" and an error object with code, message and sometimes field. It has the codes above (for example invalid_param for a row's bad value, or url_failed for a row's image URL), and these:

Code	Means
`queue_failed`	The job could not be put on the queue. Send it again.
`job_timeout`	The job ran for too long and was stopped. Its credits came back.
`job_failed`	The job failed after several tries. Its credits came back.
`not_found`	The template or its version was deleted after the job was queued.

A failed render costs nothing. Its credits come back.

Seen MintRender used for content that breaks our terms? Report it. Questions about the API: support@mintrender.com, with the request id.