Errors

HTTP status codes and error response shapes.

All errors return a standard JSON envelope with an appropriate HTTP status code:

{
  "success": false,
  "error": "Human-readable error message"
}

HTTP status codes

Code	Meaning	Common causes
400	Bad Request	Invalid template, invalid blocks (bad JSON, unknown block types, empty array), malformed UUID in path
401	Unauthorized	Missing X-API-KEY header, invalid or revoked API key
404	Not Found	Run, canvas, or task does not exist or belongs to another account
500	Internal Error	Unexpected server error — details are logged server-side and not exposed to callers

Example error responses

Invalid template (400)

{
  "success": false,
  "error": "Invalid template: foo. Valid templates: app, auto, deep_research, excel, landing_page, memo, report, slides"
}

Invalid block types (400)

{
  "success": false,
  "error": "Invalid block types: my-block. Valid block types: app-block, deep-research-block, ..."
}

Missing API key (401)

{
  "success": false,
  "error": "X-API-KEY header required"
}

Run not found (404)

{
  "success": false,
  "error": "Run not found: 550e8400-e29b-41d4-a716-446655440000"
}

Invalid UUID (400)

{
  "success": false,
  "error": "Invalid run_id: must be a valid UUID"
}

Internal error (500)

{
  "success": false,
  "error": "An internal error occurred while creating the run"
}