clockify_detailed_reports_api_docs 1.0.0

data/docs/Clockify_API_Complete.md

@@ -0,0 +1,939 @@
+# 📚 Clockify Detailed Reports API - Complete Reference
+
+## 🔗 **Endpoint**
+```
+POST https://reports.api.clockify.me/v1/workspaces/{workspaceId}/reports/detailed
+```
+**Authentication**: `X-Api-Key: YOUR_API_KEY`
+
+---
+
+## ⚡ **Quick Start (Minimal Required Call)**
+```json
+{
+  "dateRangeStart": "2024-01-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-12-31T23:59:59.999Z",
+  "detailedFilter": {
+    "page": 1,
+    "pageSize": 100
+  }
+}
+```
+
+---
+
+## 🎯 **Complete API Call Example (All Parameters)**
+
+```json
+{
+  "dateRangeStart": "2024-01-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-12-31T23:59:59.999Z",
+  
+  "detailedFilter": {
+    "page": 1,
+    "pageSize": 100,
+    "sortColumn": "DATE",
+    "auditFilter": {
+      "duration": 300,
+      "durationShorter": true,
+      "withoutProject": false,
+      "withoutTask": false
+    },
+    "options": {
+      "totals": "CALCULATE"
+    }
+  },
+  
+  "amountShown": "EARNED",
+  "amounts": ["EARNED", "COST", "PROFIT"],
+  "invoicingState": "UNINVOICED",
+  "sortOrder": "DESCENDING",
+  "exportType": "JSON",
+  "zoomLevel": "MONTH",
+  
+  "billable": true,
+  "description": "client meeting",
+  "approvalState": "APPROVED", 
+  "archived": false,
+  "rounding": true,
+  "withoutDescription": false,
+  
+  "clients": {
+    "contains": "CONTAINS",
+    "ids": ["client_id_1"],
+    "status": "ACTIVE"
+  },
+  
+  "projects": {
+    "contains": "CONTAINS",
+    "ids": ["project_id_1"], 
+    "status": "ACTIVE"
+  },
+  
+  "users": {
+    "contains": "CONTAINS",
+    "ids": ["user_id_1"],
+    "status": "ACTIVE"
+  },
+  
+  "userGroups": {
+    "contains": "CONTAINS",
+    "ids": ["group_id_1"],
+    "status": "ACTIVE"
+  },
+  
+  "tags": {
+    "containedInTimeentry": "CONTAINS",
+    "contains": "CONTAINS",
+    "ids": ["tag_id_1"],
+    "status": "ACTIVE"
+  },
+  
+  "tasks": {
+    "contains": "CONTAINS",
+    "ids": ["task_id_1"],
+    "status": "ACTIVE"
+  },
+  
+  "currency": {
+    "contains": "CONTAINS",
+    "ids": ["USD"],
+    "status": "ACTIVE"
+  },
+  
+  "attendanceFilter": {
+    "page": 1,
+    "pageSize": 201,
+    "sortColumn": "USER",
+    "hasTimeOff": true,
+    "workFilters": [
+      {
+        "filtrationType": "LARGER_THAN",
+        "value": "480"
+      }
+    ],
+    "startFilters": [
+      {
+        "filtrationType": "LARGER_THAN", 
+        "value": "09:00"
+      }
+    ],
+    "endFilters": [
+      {
+        "filtrationType": "SMALLER_THAN",
+        "value": "17:00"
+      }
+    ],
+    "breakFilters": [
+      {
+        "filtrationType": "SMALLER_THAN",
+        "value": "120"
+      }
+    ],
+    "capacityFilters": [
+      {
+        "filtrationType": "EXACTLY",
+        "value": "800"
+      }
+    ],
+    "overtimeFilters": [
+      {
+        "filtrationType": "LARGER_THAN", 
+        "value": "100"
+      }
+    ]
+  },
+  
+  "summaryFilter": {
+    "groups": ["PROJECT", "CLIENT"],
+    "sortColumn": "DURATION",
+    "summaryChartType": "PROJECT"
+  },
+  
+  "weeklyFilter": {
+    "group": "weekly_group_id",
+    "subgroup": "weekly_subgroup_id"
+  },
+  
+  "customFields": [
+    {
+      "id": "custom_field_id",
+      "type": "TXT",
+      "isEmpty": false,
+      "value": "custom_value"
+    }
+  ],
+  
+  "timeZone": "America/New_York",
+  "dateFormat": "YYYY-MM-DD",
+  "timeFormat": "THH:MM:SS.ssssss",
+  "weekStart": "MONDAY",
+  "userLocale": "en-US"
+}
+```
+
+---
+
+## 📝 **Complete Parameters Guide**
+
+### 🔴 **Required Parameters (Always Include These)**
+
+#### **dateRangeStart & dateRangeEnd**
+```json
+{
+  "dateRangeStart": "2024-01-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-12-31T23:59:59.999Z"
+}
+```
+- **Format**: Must be exact ISO 8601 format `YYYY-MM-DDTHH:MM:SS.sssZ`
+- **Time zone**: Always use `.000Z` for UTC
+- **Logic**: End date must be after start date
+- **Limits**: FREE plan limited to 366 days maximum
+- **Examples**: 
+  - Start of day: `"2024-01-01T00:00:00.000Z"`
+  - End of day: `"2024-01-31T23:59:59.999Z"`
+
+#### **detailedFilter (Required Object)**
+```json
+{
+  "detailedFilter": {
+    "page": 1,
+    "pageSize": 100,
+    "sortColumn": "DATE"
+  }
+}
+```
+- **page**: Page number (starts at 1, 0 treated as 1, negative treated as 1)
+- **pageSize**: Items per page (1-1000, 0 returns ALL data - dangerous!)
+- **sortColumn**: Optional sorting (see sort options below)
+
+**detailedFilter Sort Options**:
+- `"DATE"` - Sort by date
+- `"USER"` - Sort by user name  
+- `"DURATION"` - Sort by time length
+- `"DESCRIPTION"` - Sort by description text
+- `"ID"` - Sort by entry ID
+- `"NATURAL"` - Natural ordering
+- `"USER_DATE"` - Sort by user then date
+
+**⚠️ Critical**: Empty string `""` in sortColumn causes server crash!
+
+---
+
+### 💰 **Financial Parameters**
+
+#### **amountShown (Single Amount Type)**
+```json
+{ "amountShown": "EARNED" }
+```
+- `"EARNED"` - Revenue from billable time (client perspective)
+- `"COST"` - Internal costs/payroll (company perspective)  
+- `"PROFIT"` - Earned minus cost (profit analysis)
+- `"HIDE_AMOUNT"` - No financial data in response
+- `"EXPORT"` - For file exports
+
+**⚠️ Critical**: Empty string `""` causes server crash!
+
+#### **amounts (Multiple Amount Types)**
+```json
+{ "amounts": ["EARNED", "COST", "PROFIT"] }
+```
+- **Usage**: More efficient than multiple API calls
+- **Conflict**: If both `amountShown` and `amounts` used, `amounts` takes precedence
+- **Values**: Same options as `amountShown`
+
+#### **invoicingState (Billing Workflow)**
+```json
+{ "invoicingState": "UNINVOICED" }
+```
+- `"UNINVOICED"` - Time not yet billed to clients
+- `"INVOICED"` - Time already invoiced
+- `"ALL"` - All time regardless of invoice status
+
+**Use Case**: Generate monthly invoices by filtering uninvoiced billable time
+
+---
+
+### 📊 **Display & Output Parameters**
+
+#### **sortOrder (Result Ordering)**
+```json
+{ "sortOrder": "DESCENDING" }
+```
+- `"ASCENDING"` - Oldest first, A-Z, smallest first
+- `"DESCENDING"` - Newest first, Z-A, largest first
+
+#### **exportType (Output Format)**  
+```json
+{ "exportType": "XLSX" }
+```
+- `"JSON"` - Default, for programming
+- `"JSON_V1"` - Legacy JSON format
+- `"CSV"` - Excel/Google Sheets compatible
+- `"XLSX"` - Excel file format
+- `"PDF"` - Formatted report
+- `"ZIP"` - Compressed archive
+
+**⚠️ Gotchas**: 
+- Empty string `""` causes server crash!
+- Lowercase `"csv"` works but returns CSV data instead of JSON (breaks parsing)
+- Non-JSON formats return binary data, not JSON responses
+
+#### **zoomLevel (Aggregation)**
+```json
+{ "zoomLevel": "MONTH" }
+```
+- `"WEEK"` - Weekly aggregation
+- `"MONTH"` - Monthly aggregation  
+- `"YEAR"` - Yearly aggregation
+
+**Use Case**: High-level reporting and trend analysis
+
+---
+
+### 🎛️ **Basic Content Filters**
+
+#### **billable (Billable Status)**
+```json
+{ "billable": true }
+```
+- `true` - Only billable time (client work)
+- `false` - Only non-billable time (internal work)
+- Omit - All time entries
+
+**Business Impact**: Critical for separating client billing from internal operations
+
+#### **description (Text Search)**
+```json
+{ "description": "meeting" }
+```
+- **Search**: Case-insensitive text search within descriptions
+- **Examples**: `"bug"` finds "Bug fix", "Debug issue"
+- **Use Case**: Track specific activity types across projects
+
+#### **approvalState (Approval Workflow)**
+```json
+{ "approvalState": "APPROVED" }
+```
+- `"APPROVED"` - Manager-approved time entries
+- `"UNAPPROVED"` - Pending approval
+- `"ALL"` - All entries regardless of approval
+
+**When to use**: Organizations with time entry approval processes
+
+#### **archived (Include Archived Items)**
+```json
+{ "archived": false }
+```
+- `false` - Only active items (default)
+- `true` - Include archived projects/clients
+
+#### **rounding (Time Rounding Rules)**
+```json
+{ "rounding": true }
+```
+- `true` - Apply workspace time rounding rules (15min, 30min, etc.)
+- `false` - Exact time values
+
+**Use Case**: Organizations that bill in rounded time increments
+
+#### **withoutDescription (Quality Control)**
+```json
+{ "withoutDescription": true }
+```
+- `true` - Only entries with empty/missing descriptions
+- `false` - Only entries with descriptions
+
+**Use Case**: Data quality audits to find incomplete time entries
+
+---
+
+### 👥 **Entity Relationship Filters**
+
+All entity filters use the same structure pattern:
+
+#### **clients (Client Filter)**
+```json
+{
+  "clients": {
+    "contains": "CONTAINS",
+    "ids": ["client_id_1", "client_id_2"],
+    "status": "ACTIVE"
+  }
+}
+```
+
+#### **projects (Project Filter)**
+```json
+{
+  "projects": {
+    "contains": "CONTAINS",
+    "ids": ["project_id_1", "project_id_2"],
+    "status": "ACTIVE"
+  }
+}
+```
+
+#### **users (User Filter)**
+```json
+{
+  "users": {
+    "contains": "CONTAINS", 
+    "ids": ["user_id_1", "user_id_2"],
+    "status": "ACTIVE"
+  }
+}
+```
+
+#### **userGroups (Team/Department Filter)**
+```json
+{
+  "userGroups": {
+    "contains": "CONTAINS",
+    "ids": ["team_id_1", "team_id_2"],
+    "status": "ACTIVE"
+  }
+}
+```
+
+**userGroups Use Cases**:
+- Department reporting (Engineering, Marketing, Sales)
+- Location-based analysis (Remote vs Office)
+- Role-based filtering (Managers vs Individual Contributors)
+- Project team comparisons
+- Cost center analysis
+
+#### **tags (Tag Filter - Special Structure)**
+```json
+{
+  "tags": {
+    "containedInTimeentry": "CONTAINS",
+    "contains": "CONTAINS",
+    "ids": ["tag_id_1", "tag_id_2"],
+    "status": "ACTIVE"
+  }
+}
+```
+
+**Special Field**: `containedInTimeentry` controls how tags relate to time entries
+
+#### **tasks (Task Filter)**
+```json
+{
+  "tasks": {
+    "contains": "CONTAINS",
+    "ids": ["task_id_1", "task_id_2"],
+    "status": "ACTIVE"
+  }
+}
+```
+
+**Use Case**: Task-level time tracking analysis within projects
+
+#### **currency (Multi-Currency Filter)**
+```json
+{
+  "currency": {
+    "contains": "CONTAINS",
+    "ids": ["USD", "EUR", "GBP"],
+    "status": "ACTIVE"
+  }
+}
+```
+
+**Use Case**: International teams with multi-currency workspaces
+
+**Entity Filter Options Explained**:
+
+**contains** (Relationship Type):
+- `"CONTAINS"` - Include entries that have any of these entities
+- `"DOES_NOT_CONTAIN"` - Exclude entries that have these entities  
+- `"CONTAINS_ONLY"` - Only entries that have exactly these entities (stricter)
+
+**status** (Entity Status):
+- `"ACTIVE"` - Only currently active entities
+- `"ARCHIVED"` - Only archived/deleted entities
+- `"ALL"` - Both active and archived entities
+
+**ids** (Entity Selection):
+- Empty array `[]` - Include all entities of this type
+- Specific IDs `["id1", "id2"]` - Only these specific entities
+- `[null]` - Works (null values ignored)
+
+---
+
+### 🎯 **AttendanceFilter (Workforce Analytics)**
+
+> **🚨 CRITICAL CONCEPT**: AttendanceFilter works on **DAILY PATTERNS**, not individual entries!
+
+#### **How AttendanceFilter Works**
+1. **Groups** all time entries by date and user
+2. **Calculates** daily totals (work hours, start time, end time, breaks)
+3. **Applies** filters to each day's totals
+4. **Returns** entries only from days that pass ALL filter criteria
+
+#### **AttendanceFilter Structure**
+```json
+{
+  "attendanceFilter": {
+    "page": 1,
+    "pageSize": 201,
+    "sortColumn": "USER",
+    "hasTimeOff": true,
+    "workFilters": [{"filtrationType": "LARGER_THAN", "value": "480"}],
+    "startFilters": [{"filtrationType": "LARGER_THAN", "value": "09:00"}],
+    "endFilters": [{"filtrationType": "SMALLER_THAN", "value": "17:00"}],
+    "breakFilters": [{"filtrationType": "SMALLER_THAN", "value": "120"}],
+    "capacityFilters": [{"filtrationType": "EXACTLY", "value": "800"}],
+    "overtimeFilters": [{"filtrationType": "LARGER_THAN", "value": "100"}]
+  }
+}
+```
+
+#### **AttendanceFilter Parameters Explained**
+
+**page & pageSize**: 
+- **DIFFERENT LIMIT**: Maximum pageSize is **201** (not 1000 like detailedFilter!)
+- Error: "Maximum page size is 201"
+
+**sortColumn** (Different from main sortColumn!):
+- `"USER"` - Sort by user name
+- `"DATE"` - Sort by date
+- `"START"` - Sort by daily start time
+- `"END"` - Sort by daily end time  
+- `"BREAK"` - Sort by daily break duration
+- `"WORK"` - Sort by daily work duration
+- `"CAPACITY"` - Sort by scheduled capacity
+- `"OVERTIME"` - Sort by overtime amount
+- `"TIME_OFF"` - Sort by time off status
+
+**⚠️ Critical**: Official spec says `"NAME"` but this **fails**! Use `"USER"` instead.
+
+**hasTimeOff**:
+- `true` - Include days with PTO/vacation requests
+- `false` - Exclude days with time off
+
+**Filter Arrays** (All use same structure):
+
+**workFilters** - Filter by daily work hours:
+```json
+[{"filtrationType": "LARGER_THAN", "value": "480"}]
+```
+- **Value Format**: Hours × 100 (so "480" = 4.8 hours)
+- **Common Values**:
+  - `"60"` = 0.6 hours (36 minutes) - Very permissive
+  - `"240"` = 2.4 hours - Half day minimum  
+  - `"480"` = 4.8 hours - Standard work day minimum
+  - `"800"` = 8.0 hours - Full work day
+  - `"960"` = 9.6 hours - Overtime threshold
+
+**startFilters & endFilters** - Filter by daily start/end times:
+```json
+[{"filtrationType": "LARGER_THAN", "value": "09:00"}]
+```
+- **Value Format**: 24-hour time format (e.g., "09:00", "17:30")
+- **⚠️ Warning**: Very restrictive! If ANY entry on a day violates time criteria, ENTIRE day excluded
+- **Use Cases**: Business hours compliance, schedule adherence
+
+**breakFilters** - Filter by daily break duration:
+```json
+[{"filtrationType": "SMALLER_THAN", "value": "120"}]
+```
+- **Value Format**: Hours × 100 (so "120" = 1.2 hours)
+
+**capacityFilters** - Filter by scheduled vs actual hours:
+```json
+[{"filtrationType": "EXACTLY", "value": "800"}]
+```
+- **Value Format**: Hours × 100 (so "800" = 8.0 hours)
+
+**overtimeFilters** - Filter by overtime work:
+```json
+[{"filtrationType": "LARGER_THAN", "value": "100"}]
+```
+- **Value Format**: Hours × 100 (so "100" = 1.0 hour overtime)
+
+**filtrationType Options**:
+- `"EXACTLY"` - Days with exactly this value
+- `"LARGER_THAN"` - Days with more than this value
+- `"SMALLER_THAN"` - Days with less than this value
+
+**🔥 Surprising Behavior**: Invalid filter values are silently ignored (no error)
+
+---
+
+### 📈 **Advanced Analysis Parameters**
+
+#### **summaryFilter (Summary Reporting)**
+```json
+{
+  "summaryFilter": {
+    "groups": ["PROJECT", "CLIENT"],
+    "sortColumn": "DURATION",
+    "summaryChartType": "PROJECT"
+  }
+}
+```
+
+**groups** - **Required, 1-3 group types**:
+- `"PROJECT"` - Group by projects
+- `"CLIENT"` - Group by clients  
+- `"TASK"` - Group by tasks
+- `"TAG"` - Group by tags
+- `"DATE"` - Group by date
+- `"WEEK"` - Group by week
+- `"MONTH"` - Group by month
+- `"USER"` - Group by users
+- `"USER_GROUP"` - Group by user groups
+- `"TIMEENTRY"` - Group by individual time entries
+
+**⚠️ Critical Errors**:
+- Empty array `[]` → "Groups size must be between 1 and 3"
+- More than 3 items → Same error
+- Invalid group type → "Invalid group name"
+
+**sortColumn** - How to sort summary results:
+- `"GROUP"` - Sort by group name
+- `"DURATION"` - Sort by time duration
+- `"AMOUNT"` - Sort by amount
+- `"EARNED"` - Sort by earnings
+- `"COST"` - Sort by costs
+- `"PROFIT"` - Sort by profit
+
+**summaryChartType** - Chart visualization:
+- `"BILLABILITY"` - Billable vs non-billable breakdown
+- `"PROJECT"` - Project-based analysis
+
+#### **weeklyFilter (Weekly Pattern Analysis)**
+```json
+{
+  "weeklyFilter": {
+    "group": "group_id",
+    "subgroup": "subgroup_id"
+  }
+}
+```
+
+**Use Case**: Weekly pattern analysis and trend identification
+
+#### **customFields (Custom Field Filtering)**
+```json
+{
+  "customFields": [
+    {
+      "id": "custom_field_id",
+      "type": "TXT",
+      "isEmpty": false,
+      "numberCondition": "EQUAL",
+      "value": "custom_value"
+    }
+  ]
+}
+```
+
+**type** - Custom field types:
+- `"TXT"` - Text fields
+- `"NUMBER"` - Number fields
+- `"DROPDOWN_SINGLE"` - Single-select dropdown
+- `"DROPDOWN_MULTIPLE"` - Multi-select dropdown
+- `"CHECKBOX"` - Checkbox field
+- `"LINK"` - URL/link field
+
+**numberCondition** (for number fields):
+- `"EQUAL"` - Exactly equal
+- `"GREATER_THAN"` - Greater than value
+- `"LESS_THAN"` - Less than value
+
+**isEmpty**:
+- `true` - Find fields with no value
+- `false` - Find fields with values
+
+#### **auditFilter (Data Quality)**
+```json
+{
+  "detailedFilter": {
+    "auditFilter": {
+      "duration": 300,
+      "durationShorter": true,
+      "withoutProject": false,
+      "withoutTask": false
+    }
+  }
+}
+```
+
+**duration** - Time threshold in seconds:
+- `300` = 5 minutes
+- `3600` = 1 hour
+
+**durationShorter**:
+- `true` - Find entries shorter than duration
+- `false` - Find entries longer than duration
+
+**withoutProject**:
+- `true` - Include entries missing project assignment
+- `false` - Exclude entries without projects
+
+**withoutTask**:
+- `true` - Include entries missing task assignment
+- `false` - Exclude entries without tasks
+
+**Use Cases**: Data quality audits, find incomplete time tracking
+
+#### **options (Response Control)**
+```json
+{
+  "detailedFilter": {
+    "options": {
+      "totals": "CALCULATE"
+    }
+  }
+}
+```
+
+**totals**:
+- `"CALCULATE"` - Include totals in response (default)
+- `"EXCLUDE"` - Skip totals calculation for faster response
+
+---
+
+### 🌍 **Localization & Format Parameters**
+
+#### **timeZone (Critical for Accuracy)**
+```json
+{ "timeZone": "America/New_York" }
+```
+
+**Valid Formats**:
+- IANA timezone names: `"America/New_York"`, `"Europe/London"`, `"Asia/Tokyo"`
+- UTC: `"UTC"`
+- Surprisingly works: `"GMT+5"` (non-standard but accepted)
+
+**Invalid Examples**:
+- `"Invalid/Timezone"` → HTTP 400 "The specified report time zone is invalid"
+- `123` → Same error
+
+**Critical Impact**: 
+- AttendanceFilter daily boundaries 
+- Date/time interpretation
+- Accurate reporting for remote teams
+
+#### **dateFormat & timeFormat (Display Formatting)**
+```json
+{
+  "dateFormat": "YYYY-MM-DD",
+  "timeFormat": "THH:MM:SS.ssssss"
+}
+```
+
+**Use Case**: Localized report formatting for different regions
+
+#### **weekStart (Week Calculation)**
+```json
+{ "weekStart": "MONDAY" }
+```
+
+**Options**: `"MONDAY"`, `"TUESDAY"`, `"WEDNESDAY"`, `"THURSDAY"`, `"FRIDAY"`, `"SATURDAY"`, `"SUNDAY"`
+
+**Impact**: Affects weekly calculations and AttendanceFilter
+
+#### **userLocale (Number & Date Formatting)**
+```json
+{ "userLocale": "en-US" }
+```
+
+**Examples**: `"en-US"`, `"de-DE"`, `"fr-FR"`, `"ja-JP"`
+
+**Impact**: Number formatting, date patterns, currency display
+
+---
+
+## 📋 **Response Structure**
+```json
+{
+  "timeEntries": [
+    {
+      "id": "entry_id",
+      "userId": "user_id", 
+      "userName": "John Doe",
+      "userEmail": "john@company.com",
+      "projectId": "project_id",
+      "projectName": "Project Name",
+      "clientId": "client_id",
+      "clientName": "Client Name",
+      "timeInterval": {
+        "start": "2024-08-01T09:00:00Z",
+        "end": "2024-08-01T17:00:00Z", 
+        "duration": 28800
+      },
+      "description": "Work description",
+      "billable": true,
+      "tags": [{"id": "tag_id", "name": "Tag Name"}]
+    }
+  ],
+  "totals": [
+    {
+      "totalTime": 86400,
+      "totalBillableTime": 28800,
+      "entriesCount": 10,
+      "amounts": [
+        {
+          "amount": 50000,
+          "currency": "USD"
+        }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## 🚨 **Complete Error Reference (40+ Errors)**
+
+### **HTTP 400 - Bad Request (33 errors)**
+
+#### **Missing Required Fields**
+- `400/400`: Missing dateRangeStart, dateRangeEnd
+- `400/501`: Missing detailedFilter - "Please provide detailed filter."
+
+#### **Date Format Errors**  
+- `400/501`: Invalid date format - "Invalid date! dateRangeStart and dateRangeEnd must be present; dateRangeStart and dateRangeEnd must be in ISO date format [1996-03-15T23:59:59.999Z]"
+- `400/501`: End date before start date - "Invalid date range. dateRangeStart must be before dateRangeEnd."
+
+#### **Pagination Errors**
+- `400/400`: Page size too large - "Maximum page size is 1,000"
+- `400/400`: Invalid data types - "Could not parse JSON"
+
+#### **Sort Column Errors**
+- `400/400`: Invalid sort column - Valid options: `[ID, DESCRIPTION, USER, DURATION, DATE, NATURAL, USER_DATE]`
+- `500/500`: Empty sort column - **Server crash!**
+
+#### **Amount Parameter Errors**
+- `400/400`: Invalid amountShown - Valid options: `[EARNED, COST, PROFIT, HIDE_AMOUNT, EXPORT]`
+- `500/500`: Empty amountShown - **Server crash!**
+
+#### **Entity Filter Errors**
+- `400/400`: Invalid contains value - Valid options: `[CONTAINS, DOES_NOT_CONTAIN, CONTAINS_ONLY]`
+- `400/501`: Invalid status - "Status is not valid!"
+
+#### **AttendanceFilter Errors**
+- `400/400`: Invalid filter type - Valid options: `[EXACTLY, LARGER_THAN, SMALLER_THAN]`
+- `400/400`: Invalid time format - "Invalid time format."
+- `400/501`: **AttendanceFilter page size limit** - "Maximum page size is 201"
+
+#### **summaryFilter Errors (NEW)**
+- `400/501`: **Groups size validation** - "Groups size must be between 1 and 3"
+- `400/501`: **Invalid group name** - "Invalid group name" (must use: PROJECT, CLIENT, TASK, TAG, DATE, WEEK, MONTH, USER, USER_GROUP, TIMEENTRY)
+
+#### **Timezone Errors**
+- `400/501`: Invalid timezone - "The specified report time zone is invalid."
+
+#### **Export Type Errors**
+- `400/400`: Invalid export type - Valid options: `[JSON, JSON_V1, PDF, CSV, XLSX, ZIP]`
+- `500/500`: Empty export type - **Server crash!**
+
+#### **JSON Parsing**
+- `400/400`: Malformed JSON - "Could not parse JSON"
+
+### **HTTP 401 - Unauthorized (3 errors)**
+- `401/401`: Invalid API key - "Unauthorized"
+- `401/401`: Missing API key - "Multiple or none auth tokens present"
+- `401/401`: Invalid workspace ID - "Unauthorized"
+
+### **HTTP 500 - Server Error (3 errors)**
+- `500/500`: Empty string in sortColumn, amountShown, or exportType - "Error occurred while generating report"
+
+### **HTTP 0 - Client Error (1 error)**
+- Network/parsing exceptions when response isn't valid JSON
+
+---
+
+## ⚠️ **Critical Gotchas & Warnings**
+
+### **🔥 Server Crashes (HTTP 500)**
+**Never use empty strings in these fields - causes server crashes:**
+- `sortColumn: ""`
+- `amountShown: ""`
+- `exportType: ""`
+
+### **🎯 AttendanceFilter Special Rules**
+- **Different page size limit**: 201 (not 1000 like detailedFilter)
+- **Daily filtering**: Filters entire days, not individual entries
+- **Restrictive time filters**: One invalid time excludes the entire day
+
+### **📊 summaryFilter Requirements (NEW)**
+- `groups` array **must have 1-3 items** (cannot be empty)
+- Group IDs **cannot be empty strings**
+- More restrictive than documented
+
+### **🔄 Parameter Interactions**
+- Using both `amountShown` AND `amounts`: `amounts` takes precedence
+- `pageSize: 0` in detailedFilter: **Returns ALL data** (dangerous!)
+- Negative pagination values: Treated as defaults (works unexpectedly)
+
+### **📅 Date Range Limits**  
+- **FREE plan**: Maximum 1 year (366 days)
+- Very large ranges (40+ years): Work but may be slow
+
+### **🌐 Export Format Gotchas**
+- `exportType: "csv"` (lowercase): Works but returns CSV data instead of JSON (breaks parsing)
+- Non-JSON exports return binary data, not JSON responses
+
+---
+
+## 🎯 **Common Use Cases**
+
+### **Invoice Generation**
+```json
+{
+  "dateRangeStart": "2024-01-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-01-31T23:59:59.999Z",
+  "detailedFilter": {"page": 1, "pageSize": 1000},
+  "clients": {"contains": "CONTAINS", "ids": ["client_id"], "status": "ACTIVE"},
+  "billable": true,
+  "invoicingState": "UNINVOICED",
+  "amounts": ["EARNED"]
+}
+```
+
+### **Team Productivity Report**
+```json
+{
+  "dateRangeStart": "2024-01-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-12-31T23:59:59.999Z",
+  "detailedFilter": {"page": 1, "pageSize": 200},
+  "userGroups": {"contains": "CONTAINS", "ids": ["team_id"], "status": "ACTIVE"},
+  "attendanceFilter": {
+    "page": 1,
+    "pageSize": 201,
+    "sortColumn": "USER",
+    "workFilters": [{"filtrationType": "LARGER_THAN", "value": "480"}]
+  }
+}
+```
+
+### **Data Quality Audit**
+```json
+{
+  "dateRangeStart": "2024-01-01T00:00:00.000Z",
+  "dateRangeEnd": "2024-12-31T23:59:59.999Z",
+  "detailedFilter": {
+    "page": 1,
+    "pageSize": 1000,
+    "auditFilter": {
+      "duration": 300,
+      "durationShorter": true,
+      "withoutProject": true
+    }
+  },
+  "withoutDescription": true
+}
+```
+
+---
+
+**📊 Total Documented Errors**: 40+  
+**🔬 Based on**: Comprehensive API testing  
+**⚠️ More Accurate Than**: Official Clockify API documentation  
+**📅 Last Updated**: August 23, 2025