Error Handling API Reference

This document provides comprehensive API reference for the Error Handling System.

Overview

The Error Handling API provides endpoints for managing errors, collecting user feedback, tracking analytics, and generating reports.

Base URL

/errors

Authentication

All endpoints require authentication. Include the authorization header:

Authorization: Bearer <your-token>

Error Handling Endpoints

Handle Error

Handle an error and return user-friendly response.

Endpoint: POST /errors/handle

Request Body:

{
  "error_message": "Vector store connection failed",
  "error_type": "ConnectionError",
  "context": {
    "user_id": "user123",
    "session_id": "session456",
    "query": "How to configure the API?",
    "component": "vector_store",
    "metadata": {
      "additional_info": "any additional context"
    }
  }
}

Response:

{
  "error_id": "error_12345",
  "category": "retrieval_failure",
  "severity": "medium",
  "title": "Unable to Find Information",
  "message": "I'm having trouble accessing the knowledge base to answer your question.",
  "explanation": "This usually happens when the search system is temporarily unavailable.",
  "suggested_actions": ["retry", "reformat_input", "contact_support"],
  "workarounds": [
    "Try rephrasing your question with different keywords",
    "Wait a moment and try again"
  ],
  "escalation_required": false,
  "recovery_suggestions": [
    "Check your internet connection",
    "Try a simpler question"
  ],
  "support_ticket_id": null,
  "technical_details": null
}

Submit Error Feedback

Submit user feedback on error message helpfulness.

Endpoint: POST /errors/feedback

Request Body:

{
  "error_id": "error_12345",
  "user_id": "user123",
  "helpful": true,
  "comments": "The error message was very clear and helpful"
}

Response:

{
  "message": "Feedback submitted successfully"
}

Track Error Resolution

Track error resolution for analytics.

Endpoint: POST /errors/resolution

Request Body:

{
  "error_id": "error_12345",
  "resolution_method": "retry_with_different_parameters",
  "resolution_time_minutes": 5.0,
  "success": true
}

Response:

{
  "message": "Resolution tracked successfully"
}

Analytics Endpoints

Get Error Analytics

Get error metrics and statistics.

Endpoint: GET /errors/analytics

Query Parameters:

time_window_hours (optional): Time window in hours (default: 24)
category (optional): Filter by error category
severity (optional): Filter by error severity

Example:

GET /errors/analytics?time_window_hours=48&category=retrieval_failure

Response:

{
  "total_errors": 150,
  "errors_by_category": {
    "retrieval_failure": 45,
    "generation_timeout": 30,
    "permission_denied": 15,
    "rate_limit_exceeded": 25,
    "network_error": 20,
    "data_not_found": 15
  },
  "errors_by_severity": {
    "low": 30,
    "medium": 80,
    "high": 35,
    "critical": 5
  },
  "errors_by_component": {
    "vector_store": 45,
    "generation": 30,
    "authorization": 15,
    "rate_limiter": 25,
    "network": 20,
    "ui": 15
  },
  "error_trends": {
    "trend": "increasing",
    "recent_hourly_avg": 6.25,
    "earlier_hourly_avg": 4.5,
    "change_percentage": 38.9
  },
  "user_satisfaction": {
    "overall_satisfaction": 0.82,
    "total_feedback": 120,
    "retrieval_failure_satisfaction": 0.85,
    "generation_timeout_satisfaction": 0.78
  },
  "average_resolution_time": 12.5,
  "peak_error_times": ["14:00", "10:00", "16:00"],
  "top_error_patterns": [
    {
      "pattern": "retrieval_failure_medium",
      "count": 45,
      "percentage": 30.0
    },
    {
      "pattern": "generation_timeout_medium",
      "count": 30,
      "percentage": 20.0
    }
  ]
}

Get Error Insights

Get actionable insights from error analysis.

Endpoint: GET /errors/insights

Query Parameters:

time_window_hours (optional): Time window in hours (default: 24)

Response:

[
  {
    "insight_id": "insight_1",
    "insight_type": "high_error_rate",
    "title": "High Error Rate Detected",
    "description": "System has experienced 150 errors in the last 24 hours",
    "severity": "high",
    "recommended_actions": [
      "Investigate system health and performance",
      "Check for recent deployments or changes",
      "Review error patterns for common causes"
    ],
    "impact_score": 0.8,
    "confidence": 0.9
  },
  {
    "insight_id": "insight_2",
    "insight_type": "low_satisfaction",
    "title": "Low User Satisfaction with Error Messages",
    "description": "User satisfaction rate is 82%",
    "severity": "medium",
    "recommended_actions": [
      "Review and improve error message clarity",
      "Gather more user feedback",
      "Test error messages with users"
    ],
    "impact_score": 0.7,
    "confidence": 0.8
  }
]

Generate Error Report

Generate comprehensive error report.

Endpoint: GET /errors/report

Query Parameters:

report_type (optional): Type of report (default: "daily")
time_window_hours (optional): Time window in hours (default: 24)

Response:

{
  "report_id": "report_12345",
  "report_type": "daily",
  "time_period": {
    "start": "2024-01-15T00:00:00Z",
    "end": "2024-01-15T23:59:59Z",
    "duration_hours": 24
  },
  "summary": {
    "total_errors": 150,
    "most_common_category": "retrieval_failure",
    "most_common_severity": "medium",
    "overall_satisfaction": 0.82,
    "average_resolution_time": 12.5,
    "trend": "increasing"
  },
  "insights": [
    {
      "insight_id": "insight_1",
      "insight_type": "high_error_rate",
      "title": "High Error Rate Detected",
      "description": "System has experienced 150 errors in the last 24 hours",
      "severity": "high",
      "recommended_actions": [
        "Investigate system health and performance",
        "Check for recent deployments or changes"
      ],
      "impact_score": 0.8,
      "confidence": 0.9
    }
  ],
  "recommendations": [
    "Investigate system health and performance issues",
    "Improve error message clarity and user guidance",
    "Monitor error trends and implement preventive measures"
  ],
  "generated_at": "2024-01-15T12:00:00Z"
}

Get Dashboard Data

Get data formatted for dashboard visualization.

Endpoint: GET /errors/dashboard

Query Parameters:

time_window_hours (optional): Time window in hours (default: 24)

Response:

{
  "overview": {
    "total_errors": 150,
    "error_trend": "increasing",
    "user_satisfaction": 0.82,
    "average_resolution_time": 12.5
  },
  "charts": {
    "errors_by_category": [
      {"category": "retrieval_failure", "count": 45},
      {"category": "generation_timeout", "count": 30},
      {"category": "permission_denied", "count": 15}
    ],
    "errors_by_severity": [
      {"severity": "low", "count": 30},
      {"severity": "medium", "count": 80},
      {"severity": "high", "count": 35}
    ],
    "errors_by_component": [
      {"component": "vector_store", "count": 45},
      {"component": "generation", "count": 30},
      {"component": "authorization", "count": 15}
    ]
  },
  "insights": [
    {
      "title": "High Error Rate Detected",
      "description": "System has experienced 150 errors in the last 24 hours",
      "severity": "high",
      "recommended_actions": [
        "Investigate system health and performance",
        "Check for recent deployments or changes"
      ]
    }
  ],
  "top_error_patterns": [
    {
      "pattern": "retrieval_failure_medium",
      "count": 45,
      "percentage": 30.0
    }
  ],
  "peak_error_times": ["14:00", "10:00", "16:00"]
}

Export Endpoints

Export Metrics

Export error metrics to JSON.

Endpoint: GET /errors/export/metrics

Query Parameters:

time_window_hours (optional): Time window in hours (default: 24)

Response: JSON file download

Export Report

Export error report to JSON.

Endpoint: GET /errors/export/report

Query Parameters:

report_type (optional): Type of report (default: "daily")
time_window_hours (optional): Time window in hours (default: 24)

Response: JSON file download

Health Check

Error Handling Health

Check health of error handling system.

Endpoint: GET /errors/health

Response:

{
  "status": "healthy",
  "error_handler": "initialized",
  "analytics_dashboard": "initialized",
  "timestamp": "2024-01-15T12:00:00Z"
}

Error Categories

Category	Description
`retrieval_failure`	Issues accessing knowledge base
`generation_timeout`	Response generation taking too long
`permission_denied`	Access restrictions
`rate_limit_exceeded`	Too many requests
`authentication_failed`	Login/session issues
`network_error`	Connection problems
`data_not_found`	No relevant information found
`configuration_error`	System configuration issues
`unknown_error`	Unclassified errors

Error Severity Levels

Severity	Description
`low`	Minor issues, minimal impact
`medium`	Moderate issues, some user impact
`high`	Significant issues, major user impact
`critical`	System-breaking issues, immediate attention required

Resolution Actions

Action	Description
`retry`	Try the operation again
`reformat_input`	Modify the input format
`contact_support`	Contact human support
`check_permissions`	Verify user permissions
`wait_and_retry`	Wait before retrying
`use_alternative`	Use an alternative approach
`escalate`	Escalate to higher level support

HTTP Status Codes

Code	Description
200	Success
400	Bad Request - Invalid input
401	Unauthorized - Authentication required
403	Forbidden - Insufficient permissions
404	Not Found - Resource not found
500	Internal Server Error - Server error
503	Service Unavailable - Service temporarily unavailable

Rate Limiting

The API implements rate limiting to ensure fair usage:

Error Handling: 100 requests per minute per user
Analytics: 50 requests per minute per user
Export: 10 requests per minute per user

Rate limit headers are included in responses:

X-RateLimit-Limit: Maximum requests allowed
X-RateLimit-Remaining: Remaining requests in current window
X-RateLimit-Reset: Time when the rate limit resets

Error Responses

When an error occurs, the API returns a JSON response with error details:

{
  "error": "Error message",
  "error_code": "ERROR_CODE",
  "details": "Additional error details",
  "timestamp": "2024-01-15T12:00:00Z"
}

SDK Examples

Python

import requests

# Handle an error
response = requests.post('/errors/handle', json={
    'error_message': 'Vector store connection failed',
    'error_type': 'ConnectionError',
    'context': {
        'user_id': 'user123',
        'query': 'How to configure the API?',
        'component': 'vector_store'
    }
})

error_data = response.json()
print(f"Error message: {error_data['message']}")
print(f"Suggested actions: {error_data['suggested_actions']}")

# Submit feedback
requests.post('/errors/feedback', json={
    'error_id': error_data['error_id'],
    'user_id': 'user123',
    'helpful': True,
    'comments': 'Very helpful message'
})

# Get analytics
analytics = requests.get('/errors/analytics?time_window_hours=24').json()
print(f"Total errors: {analytics['total_errors']}")

JavaScript

// Handle an error
const errorResponse = await fetch('/errors/handle', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token
  },
  body: JSON.stringify({
    error_message: 'Vector store connection failed',
    error_type: 'ConnectionError',
    context: {
      user_id: 'user123',
      query: 'How to configure the API?',
      component: 'vector_store'
    }
  })
});

const errorData = await errorResponse.json();
console.log('Error message:', errorData.message);
console.log('Suggested actions:', errorData.suggested_actions);

// Submit feedback
await fetch('/errors/feedback', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token
  },
  body: JSON.stringify({
    error_id: errorData.error_id,
    user_id: 'user123',
    helpful: true,
    comments: 'Very helpful message'
  })
});

// Get analytics
const analytics = await fetch('/errors/analytics?time_window_hours=24').then(r => r.json());
console.log('Total errors:', analytics.total_errors);

Webhooks

The API supports webhooks for real-time notifications:

Error Escalation Webhook

Triggered when an error is escalated to human support.

URL: POST /webhooks/error-escalation

Payload:

{
  "error_id": "error_12345",
  "support_ticket_id": "TICKET-ABC123",
  "category": "permission_denied",
  "severity": "high",
  "user_id": "user123",
  "timestamp": "2024-01-15T12:00:00Z"
}

High Error Rate Alert Webhook

Triggered when error rate exceeds threshold.

URL: POST /webhooks/high-error-rate

Payload:

{
  "error_count": 150,
  "threshold": 100,
  "time_window_hours": 24,
  "timestamp": "2024-01-15T12:00:00Z"
}

Changelog

Version 1.0.0

Initial release
Error classification and user-friendly messaging
Analytics and reporting
A/B testing framework
User feedback collection
Escalation management

Overview​

Base URL​

Authentication​

Error Handling Endpoints​

Handle Error​

Submit Error Feedback​

Track Error Resolution​

Analytics Endpoints​

Get Error Analytics​

Get Error Insights​

Generate Error Report​

Get Dashboard Data​

Export Endpoints​

Export Metrics​

Export Report​

Health Check​

Error Handling Health​

Error Categories​

Error Severity Levels​

Resolution Actions​

HTTP Status Codes​

Rate Limiting​

Error Responses​

SDK Examples​

Python​

JavaScript​

Webhooks​

Error Escalation Webhook​

High Error Rate Alert Webhook​

Changelog​

Version 1.0.0​

Overview

Base URL

Authentication

Error Handling Endpoints

Handle Error

Submit Error Feedback

Track Error Resolution

Analytics Endpoints

Get Error Analytics

Get Error Insights

Generate Error Report

Get Dashboard Data

Export Endpoints

Export Metrics

Export Report

Health Check

Error Handling Health

Error Categories

Error Severity Levels

Resolution Actions

HTTP Status Codes

Rate Limiting

Error Responses

SDK Examples

Python

JavaScript

Webhooks

Error Escalation Webhook

High Error Rate Alert Webhook

Changelog

Version 1.0.0