Errors

All v1 JSON errors use a flat body:

{
  "error": "Human-readable message",
  "code": "VALIDATION_ERROR",
  "details": {}
}

details is optional and only present when useful (layer validation, duplicates, hints).

Codes

Code	Typical HTTP	Meaning
UNAUTHORIZED	401	Missing or invalid API key / session
BAD_REQUEST	400	Malformed request (missing template, bad version, empty batch)
NOT_FOUND	404	Design, version, render, batch, or asset missing
VALIDATION_ERROR	422	Invalid layers, repeat expansion, or unsupported options
DUPLICATE_LAYER_NAMES	422	Template has duplicate API layer names
PAYMENT_REQUIRED	402	Plan quota exceeded
FORBIDDEN	403	Plan/feature not allowed
RATE_LIMITED	429	Too many requests; see Retry-After
QUEUE_UNAVAILABLE	503	Render could not be enqueued
GONE	410	Archived render file; re-render

Notes

• Rate-limited responses include a Retry-After header (seconds).
• Signed GET /api/v1/img/{template} that is still rendering returns 503 with Retry-After (plain text, not JSON) so <img> / crawlers retry.
• transparent: true is only valid with format: png, webp, or avif.
• Asset downloads (GET /renders/{id}/asset) stream bytes (HTTP 200). Authenticate with an API key, or pass sig from the job’s assetUrl for an unauthenticated, long-lived fetch. Archived files return 410.