Error Handling

Response Codes

Code	Meaning	When
200	Success	Request completed normally
201	Created	Template or ThemePack registered
400	Bad Request	Missing fields, malformed JSON
401	Unauthorized	Missing or invalid `x-api-key`
404	Not Found	Resource does not exist
409	Conflict	Video not ready yet
422	Unprocessable	Compilation failed — check diagnostics
429	Rate Limited	Exceeded 10 requests/minute
500	Server Error	Internal error
501	Not Implemented	LLM provider not configured
502	Bad Gateway	LLM provider error

Compilation errors (422) include a diagnostics array:

json

{
  "error": "Compilation failed",
  "diagnostics": [
    { "level": "error", "message": "Unknown mood: nonexistent", "line": 2, "column": 9 }
  ]
}

json

{ "error": "Rate limit exceeded", "retryAfter": 12 }