Error Handling

Error Response Format

{
  "error": "Error Type",
  "message": "Human-readable description of what went wrong.",
  "statusCode": 400
}

Validation errors may return an array for message:

{
  "error": "Validation Error",
  "message": [{ "path": ["name"], "message": "Required" }],
  "statusCode": 400
}

Common HTTP Error Codes

Code	Meaning	Common Causes
400	Bad Request	Missing required fields, invalid types, reserved model names, no fields to update
401	Unauthorized	Missing, expired, or invalid JWT access token
403	Forbidden	Non-admin accessing /admin/api/*, file access without ownership or valid signed URL
404	Not Found	Unknown table name, record ID not found, agent not found, file not found
409	Conflict	Email already registered, model name already exists
413	Payload Too Large	File exceeds per-request size limit or per-user storage quota
500	Internal Server Error	Unexpected server error, LLM provider failure