Errors#

All errors return JSON with a code and message:

{
  "code": "TEMPLATE_NOT_FOUND",
  "message": "Template not found or not accessible"
}

Authentication errors#

These can be returned by any authenticated endpoint.

HTTP	Code	Meaning
401	`MISSING_API_KEY`	No `Authorization` header or malformed
401	`INVALID_API_KEY`	Key not found in database
403	`KEY_INACTIVE`	Key has been revoked
402	`NO_SUBSCRIPTION`	No quota record for this user
402	`SUBSCRIPTION_INACTIVE`	Subscription expired or canceled

HTTP	Code	Meaning
400	`INVALID_BODY`	Body is not valid JSON
400	`MISSING_TEMPLATE_ID`	`templateId` is required
400	`INVALID_VARIABLES`	`variables` must be an object
400	`INVALID_WIDTH`	Width must be 1–4096
400	`INVALID_HEIGHT`	Height must be 1–4096
400	`INVALID_FORMAT`	Must be `png`, `jpeg`, or `webp`
400	`INVALID_DEVICE_PIXEL_RATIO`	Must be a positive number
404	`TEMPLATE_NOT_FOUND`	Template doesn't exist or not accessible
400	`MISSING_TEMPLATE_VARIABLES`	Required variables not provided
400	`TEMPLATE_NOT_COMPILED`	Template has no compiled render plan
429	`QUOTA_EXCEEDED`	Monthly image quota exhausted
500	`SERVER_ERROR`	Internal error (e.g. signing secret not configured)

HTTP	Code	Meaning
400	`INVALID_BODY`	Body is not valid JSON
400	`INVALID_ITEMS`	`items` must be an array
400	`EMPTY_ITEMS`	`items` array is empty
400	`TOO_MANY_ITEMS`	More than 25 items
400	`MISSING_TEMPLATE_ID`	`items[n].templateId` is required
400	`INVALID_VARIABLES`	`items[n].variables` must be an object
400	`INVALID_WIDTH`	`items[n]` width must be 1–4096
400	`INVALID_HEIGHT`	`items[n]` height must be 1–4096
400	`INVALID_FORMAT`	Unsupported image format
400	`INVALID_DEVICE_PIXEL_RATIO`	Must be a positive number
404	`TEMPLATE_NOT_FOUND`	Template doesn't exist or not accessible
400	`TEMPLATE_NOT_COMPILED`	Template has no compiled render plan
429	`QUOTA_EXCEEDED`	Monthly image quota exhausted
500	`SERVER_ERROR`	Internal error

HTTP	Code	Meaning
400	`INVALID_SCOPE`	Must be `all`, `mine`, or `starter`
500	`TEMPLATES_LIST_FAILED`	Template list query failed

HTTP	Code	Meaning
400	`INVALID_JSON`	Body is not valid JSON
400	`MISSING_NAME`	`name` is required
400	`MISSING_CODE`	`code` is required
400	`INVALID_CODE`	Code exceeds size limit (180K chars)
400	`LEGACY_TEMPLATE_PAYLOAD`	Old-style fields (`jsx`, `googleFonts`, etc.) were sent — use `code` instead
400	`COMPILE_ERROR`	Template code failed to compile
500	`TEMPLATE_CREATE_FAILED`	Creation failed

HTTP	Code	Meaning
400	`INVALID_JSON`	Body is not valid JSON
400	`INVALID_ITEMS`	`items` must be an array
400	`EMPTY_ITEMS`	`items` array is empty
400	`TOO_MANY_ITEMS`	More than 5 items
429	`QUOTA_EXCEEDED`	Monthly AI generation quota exhausted
402	`SUBSCRIPTION_REQUIRED`	Paid plan required for AI generation
422	`PARSE_FAILED`	Generated code could not be parsed
502	`AI_NOT_CONFIGURED`	AI service is not available
502	`GENERATION_FAILED`	AI generation failed

HTTP	Code	Meaning
400	`MISSING_TEMPLATE_ID`	No template ID in the URL path
404	`TEMPLATE_NOT_FOUND`	Template doesn't exist or not accessible
500	`TEMPLATE_FETCH_FAILED`	Lookup failed

HTTP	Code	Meaning
400	`MISSING_TEMPLATE_ID`	No template ID in the URL path
400	`INVALID_JSON`	Body is not valid JSON
400	`EMPTY_UPDATE`	No fields provided to update
400	`INVALID_NAME`	Name is invalid
400	`INVALID_CODE`	Code exceeds size limit
400	`LEGACY_TEMPLATE_PAYLOAD`	Old-style fields sent — use `code` instead
400	`COMPILE_ERROR`	Updated code failed to compile
404	`TEMPLATE_NOT_FOUND`	Template doesn't exist or not yours
500	`TEMPLATE_UPDATE_FAILED`	Update failed

HTTP	Code	Meaning
403	`URL_EXPIRED`	Signed URL has expired
403	`INVALID_SIGNATURE`	Signature doesn't match
404	`VNODE_NOT_FOUND`	Render data missing for this URL
400	`MAX_DEPTH`	Nested render depth exceeded
500	`RENDER_ERROR`	Image render failed
500	`INVALID_VNODE`	Stored render data is corrupted