Standardize API response structure and fix inconsistent error handling

[Copilot]

The API had inconsistent response formats—success responses returned raw data while errors returned {"error": "message"}, the reset endpoint returned nil, and errors lacked machine-readable codes. The frontend displayed hardcoded generic messages instead of server-provided details.

Backend Changes

Added standardized response types:

type APIResponse struct {
    Success bool        `json:"success"`
    Message string      `json:"message,omitempty"`
    Data    interface{} `json:"data,omitempty"`
    Error   *APIError   `json:"error,omitempty"`
}

type APIError struct {
    Code    string `json:"code"`
    Message string `json:"message"`
    Details string `json:"details,omitempty"`
}

Updated all endpoints to return consistent responses:

• createCollection: Returns {success, message, data: {name, created_at}}
• reset: Fixed return nil → returns {success, message, data: {collection, reset_at}}
• search: Removed debug fmt.Println(r), wraps results with query metadata
• All error responses include error codes: NOT_FOUND, INVALID_REQUEST, INTERNAL_ERROR, UNAUTHORIZED, CONFLICT

Frontend Changes

Added global response handler:

function handleAPIResponse(response) {
  return response.json().then(data => {
    if (!response.ok || (data.success === false)) {
      const error = new Error(data.error?.message || 'Operation failed');
      error.code = data.error?.code;
      error.details = data.error?.details;
      throw error;
    }
    return data;
  });
}

Updated all fetch handlers to extract and display server-provided messages from data.message and data.error.message.

Example Responses

Success:

{
  "success": true,
  "message": "Collection created successfully",
  "data": {
    "name": "test-collection",
    "created_at": "2026-01-12T22:13:20Z"
  }
}

Error:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Collection not found",
    "details": "Collection 'nonexistent' does not exist"
  }
}

Original prompt

Problem

The current API implementation has inconsistent error handling and JSON response structures:

Backend Issues (routes.go)

1. Inconsistent JSON Response Structure:

   • Success responses return raw data (e.g., collection, results, arrays)
   • Error responses return {"error": "message"}
   • No consistent wrapper for operation results

2. Missing Success Indicators: When creating a collection (createCollection), the API returns the raw collection object with no success, message, or operation status fields.

3. No Response on Reset: The reset() function returns nil (no response body at all) on line 154:

   return nil  // returns empty response - should return proper JSON

4. Debug Code in Production: There's a fmt.Println(r) in the search() function (line 176) that should be removed.

5. No Error Codes: Errors only contain messages, no error codes for programmatic handling by clients.

Frontend Issues (static/js/collectionManager.js)

1. Generic Error Messages: The frontend shows hardcoded generic messages like "Failed to create collection" instead of server-provided error details.

2. Error Details Not Extracted: While the search function attempts to parse error JSON, other functions like createCollection, uploadFile, resetCollection don't properly extract and display server error messages.

3. No Operation Result Feedback: For successful operations, there's no confirmation of what was actually done.

Required Changes

1. Create Standardized API Response Structure

Add new types to routes.go:

// APIResponse represents a standardized API response
type APIResponse struct {
    Success bool        `json:"success"`
    Message string      `json:"message,omitempty"`
    Data    interface{} `json:"data,omitempty"`
    Error   *APIError   `json:"error,omitempty"`
}

// APIError represents a detailed error response
type APIError struct {
    Code    string `json:"code"`
    Message string `json:"message"`
    Details string `json:"details,omitempty"`
}

2. Add Helper Functions and Error Codes

// Error codes
const (
    ErrCodeNotFound       = "NOT_FOUND"
    ErrCodeInvalidRequest = "INVALID_REQUEST"
    ErrCodeInternalError  = "INTERNAL_ERROR"
    ErrCodeUnauthorized   = "UNAUTHORIZED"
    ErrCodeConflict       = "CONFLICT"
)

func successResponse(message string, data interface{}) APIResponse {
    return APIResponse{
        Success: true,
        Message: message,
        Data:    data,
    }
}

func errorResponse(code string, message string, details string) APIResponse {
    return APIResponse{
        Success: false,
        Error: &APIError{
            Code:    code,
            Message: message,
            Details: details,
        },
    }
}

3. Update All Route Handlers

Update all handlers in routes.go to use the new response format:

• createCollection: Return success response with collection name and created_at timestamp
• reset: Fix the return nil issue - return proper JSON success response
• uploadFile: Return success response with filename and collection info
• deleteEntryFromCollection: Return success response with remaining entries
• registerExternalSource: Already returns a message, but should use new format
• removeExternalSource: Already returns a message, but should use new format
• search: Remove fmt.Println(r) debug statement, wrap results in response format
• All error cases: Use errorResponse() with appropriate error codes

4. Update Frontend Error Handling

Update static/js/collectionManager.js:

• Add a utility function to handle API responses consistently
• Update createCollection() to parse and display server-provided messages
• Update uploadFile() to show detailed error messages
• Update resetCollection() to show server response messages
• Update fetchCollections(), listEntries(), and other functions similarly

Example updated fetch handler pattern:

.then(response => response.json())
.then(data => {
    if (!data.success) {
        throw {
            code: data.error?.code,
            message: data.error?.message,
            details: data.error?.details
        };
    }
    this.showToast('success', data.message);
    // ... rest of success handling
})
.catch(error => {
    const message = error.message || 'Operation failed';
    this.showToast('error', message);
})

Files to Modify

1. routes.go - Add response types, helper functions, error codes, and update all handlers
2. static/js/collectionManager.js - Update all fetch handlers to use new response format

Expected Outcome

After these changes:

• All API endpoints return consistent JSON with success, message, data, and error fields
• Errors include machine-readable error codes for programmatic handling
• The frontend displays meaningful, server-provided error and success messages
• The reset endpoint returns a proper re...

This pull request was created from Copilot chat.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.