Errors

When a request fails, the API answers with a status code of 400 or more and a JSON body that says why. This page lists every code you can get and what to do about it.

The error shape

Every error has the same shape:

{
  "error": "WORKSPACE_QUOTA_EXCEEDED",
  "message": "Workspace quota exceeded: requested 3, remaining 1 of 500",
  "detail": {
    "limit": 500,
    "used": 499,
    "requested": 3,
    "remaining": 1,
    "periodEnd": "2027-01-01T00:00:00.000Z"
  }
}

Field	What it is
error	A code that never changes, such as WORKSPACE_QUOTA_EXCEEDED. Check this in your code.
message	A sentence that explains the problem. It is safe to show to your users, but it can change, so don’t check it in code.
detail	Optional. More facts about the error, such as the credits left. Its fields depend on the code.

A failed request costs no credits. A failed render costs no render credits and no AI credits.

400 Bad Request

error	Meaning	What to do
VALIDATION_ERROR	The request is wrong: a missing or bad field, a page that doesn’t exist, a style the layer doesn’t take, a limit passed.	Read message. When the body itself is wrong, detail.issues lists each problem with its path. For workflows, detail.problems lists what’s missing.
INVALID_REQUEST	The body isn’t valid JSON, or couldn’t be read.	Check that you send JSON with Content-Type: application/json.
WEBHOOK_URL_INVALID	A webhook URL isn’t https, isn’t valid, or points to a private address.	Use a public https URL.

401 Unauthorized

error	Meaning	What to do
MISSING_API_KEY	No Authorization header, or it doesn’t use Bearer.	Send Authorization: Bearer jf_live_….
INVALID_API_KEY	The key is wrong or was revoked, or the person who made it no longer has editor access to the workspace.	Check the key, or make a new one. See API keys.

402 Payment Required

error	Meaning	What to do
QUOTA_EXCEEDED	Your organization’s render credits for this period are used up, or its plan isn’t active.	Wait for the next period (detail.periodEnd). If you need more credits sooner, contact us. See Credits.
WORKSPACE_QUOTA_EXCEEDED	This workspace has used the credit cap an organization admin set for it.	Ask an admin to raise the workspace’s cap.
PLAN_LIMIT_EXCEEDED	A plan limit other than credits, such as workflows, steps in a workflow, or workflow runs this month. detail.limitKey names it.	Remove something, or wait for next month. See Pricing.
AI_CREDITS_EXCEEDED	Your organization’s AI credits for this period are used up.	Wait for the next period, or render without AI.
WEBHOOK_LIMIT_REACHED	The workspace already has 20 webhooks.	Delete one you don’t use.

403 Forbidden

error	Meaning	What to do
ORG_ON_HOLD	Your organization is on hold while JamFrame reviews recent activity. Reading still works (GET), but renders and changes are refused.	Contact support.
ORG_SUSPENDED	Your organization is suspended. Nothing works.	Contact support if you think this is a mistake.

404 Not Found

error	Meaning	What to do
NOT_FOUND	No template, render, workflow, run, job or webhook with this id in the workspace of your key.	Check the id, and that you use a key of the right workspace.

409 Conflict

error	Meaning	What to do
CONFLICT	The thing is not in a state that allows this: for example, canceling a workflow run that already ended, or calling the incoming webhook of a draft workflow.	Read message. Nothing changed.

413, 415 and 422

Status	error	Meaning	What to do
413	BODY_TOO_LARGE	The JSON body is over 5 MB.	Send image links instead of image data.
413	VALIDATION_ERROR	An uploaded file is far too large.	Keep uploads under 10 MB.
415	UNSUPPORTED_MEDIA_TYPE	The body uses a character set or encoding JamFrame can’t read.	Send UTF-8 JSON.
422	VALIDATION_ERROR	An image link in the template or in your values didn’t load, or isn’t allowed. message names the link.	Check that the link is public and points to an image.
422	AI_CONTENT_REFUSED	The AI provider refused the prompt or the result under its content policy.	Change the prompt.
422	AI_BAD_REQUEST	The AI provider couldn’t use this input, such as an image it can’t read.	Try another input.

429 Too Many Requests

error	Meaning	What to do
RATE_LIMITED	Too many requests: your per-minute limit, or an endpoint’s own limit.	Wait for the Retry-After header (or detail.retryAfter) in seconds, then try again. See Rate limits.
AI_RATE_LIMITED	The AI provider is busy.	Wait a moment and try again.

500 and above

Status	error	Meaning	What to do
500	INTERNAL	Something went wrong on JamFrame’s side, or a render failed or took too long.	Try again. If it keeps happening, contact support with the time and the renderId if you have one.
502	AI_BAD_OUTPUT	The AI answered, but not with something usable.	Try again, maybe with a clearer prompt.
502	AI_UPSTREAM_ERROR	The AI provider failed.	Try again.
503	AI_UNAVAILABLE	AI is off right now.	Try later. For renders, "ai": { "onError": "fallback" } renders without AI.
504	AI_TIMEOUT	The AI didn’t answer in time.	Try again.

For the AI codes in a render, see AI text, images and translation.

Errors on public links and forms

Signed URLs, dynamic URLs and forms are opened without an API key, so they answer with their own codes: INVALID_PARAMETERS, CREDIT_CAP_REACHED, CREDITS_EXHAUSTED, INVALID_SIGNATURE, UNAVAILABLE, NOT_FOUND, URL_EXPIRED, URL_DISABLED, MEDIA_UNAVAILABLE, RATE_LIMITED, RENDER_FAILED and BUSY. Forms say FORM_DISABLED and FORM_EXPIRED instead of the two URL_ codes, and add INVALID_VALUES, CAPTCHA_FAILED, CAPTCHA_UNAVAILABLE, UPLOAD_INVALID, UPLOAD_TOO_LARGE, UPLOADS_UNAVAILABLE and FILE_EXPIRED, which visitors see as messages on the form. For what each one means, see the tables for dynamic URLs, signed URLs and forms.

Which errors to retry

• Retry later: 429, 500, 502, 503 and 504. Wait between tries, longer each time. See Rate limits.
• Don’t retry as is: other 4xx codes. The same request will fail again until you change it, or until your credits come back.

A retried render can make the file twice if the first try actually worked. For long renders, use async renders and keep the job id.

Warnings are not errors

A render can succeed and still have a warnings list next to data. The file was made, and credits were charged as usual. Warnings tell you about something you may want to fix:

{
  "data": { "content": "https://cdn.jamframe.com/renders/…", "credits": 1 },
  "warnings": [
    "Unknown modification keys (no matching layer or {{placeholder}}): headlin"
  ]
}

Common warnings:

• A key in modifications that matches no layer or variable, often a typo. It is ignored. (The warning says “placeholder” for a variable: a {{name}} in text.)
• A {{name}} in an AI prompt that had no value.
• An AI step that failed with "onError": "fallback", so the saved text or image was used.
• Text that couldn’t be translated and stayed in the original language.

Workflow runs have warnings too, for example when a source had more rows than a run can take.

Related

• Limits and how to back off: Rate limits
• Credits and what they cost: Credits
• Fixes for common problems: Troubleshooting