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

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.