Skip to content

Error Handling

GoVector is a high-performance embedded vector database that provides a Qdrant-compatible REST API interface. This guide focuses on the error handling mechanism in the system, detailing all possible HTTP status codes, triggering conditions, error response formats, and diagnosis and resolution methods.

Error Status Code Overview

GoVector API supports the following standard HTTP status codes:

  • 200 OK - Request successfully executed
  • 400 Bad Request - Invalid request format or parameters
  • 404 Not Found - Specified resource does not exist
  • 409 Conflict - Resource conflict (such as duplicate creation)
  • 500 Internal Server Error - Server internal error
flowchart TD
A["API Request"] --> B{"Status Code Type"}
B --> |2xx| C["Success Response
Return business data"]
B --> |400| D["Client Error
Invalid request"]
B --> |404| E["Resource not found
Collection/point does not exist"]
B --> |409| F["Conflict error
Duplicate creation"]
B --> |500| G["Server error
Internal exception"]
D --> H["Check request format
Validate parameters"]
E --> I["Confirm resource exists
Check collection name"]
F --> J["Avoid duplicate operations
Query before creating"]
G --> K["Check logs
Inspect system status"]

HTTP Status Code Details

200 OK - Success Response

Trigger Conditions: - All successful API calls - Collection management operations completed successfully - Vector operations executed successfully

Response Characteristics: - Returns standard JSON response format - Contains status field with value "ok" - Contains specific business results in result field

400 Bad Request - Request Error

Trigger Conditions: - Invalid JSON format - Missing required request parameters - Incorrect parameter types - Vector dimension mismatch

Specific Scenarios:

  1. Invalid JSON Format
  2. Request body is not valid JSON

  3. Field type does not match expectation

  4. Parameter Validation Failed

  5. Collection name is empty or malformed
  6. Vector size must be a positive number

  7. Distance metric parameter is invalid

  8. Data Format Error

  9. Vector dimension in vector array does not match collection definition
  10. Query vector dimension is incorrect

404 Not Found - Resource Does Not Exist

Trigger Conditions: - Accessing a collection that does not exist - Operating on a collection that does not exist - Deleting a point that does not exist

Specific Scenarios:

  1. Collection Does Not Exist
  2. Attempting to access a collection that has not been created

  3. Using incorrect collection name

  4. Point Does Not Exist

  5. Deleting a point ID that does not exist

  6. Searching in a collection that does not exist

  7. Path Parameter Error

  8. Collection name misspelled
  9. URL path is incorrect

409 Conflict - Conflict Error

Trigger Conditions: - Attempting to create a collection that already exists - Resource state conflict

Specific Scenarios: - Duplicate creation of collection with same name - State conflict caused by concurrent operations

500 Internal Server Error - Internal Error

Trigger Conditions: - Storage engine operation failure - Index update failure - Database connection problem - Insufficient system resources

Specific Scenarios:

  1. Storage Layer Error
  2. Database failed to open
  3. Data persistence failed

  4. Metadata save failed

  5. Index Layer Error

  6. Vector index update failed
  7. Search operation exception

  8. Point deletion failed

  9. System-Level Error

  10. Insufficient memory
  11. File permission problem
  12. Network connection exception

Error Response Format

Standard Error Response Structure

All error responses follow a unified JSON format:

{
  "status": "error",
  "result": {
    "message": "Error description message",
    "code": "Error code",
    "details": "Detailed error context information"
  }
}

Success Response Structure

Successful responses use the same structure, but status is "ok":

{
  "status": "ok",
  "result": {
    "operation": "completed",
    "data": "Business data"
  }
}

Field Description

Field Name Type Required Description
status string Yes Response status, "ok" for success, "error" for error
result object Yes Response result object
message string Yes Error description message
code string No Error code identifier
details string No Detailed error context information

Common Error Scenarios and Diagnosis

1. Invalid JSON Format

Trigger Conditions: - Request body is not valid JSON - Field type does not match expectation - Missing required fields

Diagnosis Steps: 1. Verify JSON format correctness 2. Check if required fields exist 3. Confirm field types match API documentation

Solutions: - Use online JSON validation tools - Reference API documentation request examples - Implement client-side data validation

2. Collection Does Not Exist

Trigger Conditions: - Accessing a collection name that does not exist - Operating on a collection that has not been created

Diagnosis Steps: 1. Use GET /collections to list all collections 2. Verify collection name spelling 3. Check if collection was correctly created

Solutions: - Create collection before operating - Implement collection existence check - Use idempotent operations to ensure collection exists

3. Parameter Validation Failed

Trigger Conditions: - Vector size is negative or zero - Distance metric parameter is invalid - Query parameter format is incorrect

Diagnosis Steps: 1. Check vector dimension settings 2. Verify distance metric validity 3. Confirm query parameter completeness

Solutions: - Implement parameter range validation - Provide default parameter values - Add input format validation

4. Data Dimension Mismatch

Trigger Conditions: - Vector dimension in vector array does not match collection definition - Query vector dimension is inconsistent with collection configuration

Diagnosis Steps: 1. Check collection's vector dimension configuration 2. Verify all vector dimension consistency 3. Confirm query vector dimension

Solutions: - Validate dimensions before data insertion - Implement automatic dimension checking - Provide clear error messages

5. Storage Operation Failed

Trigger Conditions: - Database connection problem - Insufficient file permissions - Insufficient disk space

Diagnosis Steps: 1. Check database file permissions 2. Verify sufficient disk space 3. Confirm database file is accessible

Solutions: - Implement storage connection retry - Add disk space monitoring - Provide storage status check

Error Logging and Debugging

Logging Strategy

GoVector logs detailed error information at critical error points:

  1. Startup Phase Errors
  2. Storage initialization failed

  3. Collection loading exception

  4. Runtime Errors

  5. API call failed

  6. Data operation exception

  7. System-Level Errors

  8. Insufficient resources
  9. Permission problems

Debugging Tips

Enable detailed logging: 

# Set environment variable for more detailed log output
export GOVECTOR_LOG_LEVEL=debug

Use testing tools: 

# Use curl for manual testing
curl -X POST "http://localhost:18080/collections" \
  -H "Content-Type: application/json" \
  -d '{"name":"test","vector_size":128,"distance":"cosine"}'

Best Practices and Retry Strategy

Client Retry Strategy

Exponential backoff retry: 

sequenceDiagram
participant Client as Client
participant Server as Server
participant Storage as Storage
Client->>Server : Send request
Server->>Storage : Execute storage operation
Storage-->>Server : Return error
Server-->>Client : 500 Internal Server Error
Note over Client : Wait 1 second and retry
Client->>Server : Retry request
Server->>Storage : Execute storage operation again
Storage-->>Server : Success
Server-->>Client : 200 OK

Retry parameter recommendations: - Maximum retry attempts: 3-5 - Initial wait time: 1-2 seconds - Backoff multiplier: 2 - Maximum wait time: 30-60 seconds

Error Handling Best Practices

1. Client implementation essentials: - Implement idempotent operations - Add timeout control - Distinguish between retryable and non-retryable errors - Log retry history

2. Server implementation essentials: - Provide detailed error information - Implement graceful degradation - Add health checks - Monitor error rates

3. Configuration management: 

retry_policy:
  max_attempts: 3
  base_delay: 1000
  max_delay: 30000
  backoff_multiplier: 2

error_handling:
  log_level: warn
  timeout: 30000
  circuit_breaker:
    enabled: true
    threshold: 5
    timeout: 60000

Architecture-Level Error Handling

Error Propagation Chain

graph TB
subgraph "Client Layer"
A[HTTP Client]
end
subgraph "API Layer"
B[Server.handleUpsert]
C[Server.handleSearch]
D[Server.handleDelete]
end
subgraph "Core Layer"
E[Collection.Upsert]
F[Collection.Search]
G[Collection.Delete]
end
subgraph "Storage Layer"
H[Storage.UpsertPoints]
I[Storage.LoadCollection]
J[Storage.DeletePoints]
end
A --> B
A --> C
A --> D
B --> E
C --> F
D --> G
E --> H
F --> I
G --> J

Error Classification and Handling Strategy

Retryable errors: - Network connection timeout - Database temporarily unavailable - Resource competition conflict

Non-retryable errors: - Request parameter format error - Resource does not exist - Insufficient permissions

Troubleshooting Guide

Common Problem Diagnosis Flow

flowchart TD
A["Received error response"] --> B{"Status code type"}
B --> |400| C["Check request format"]
B --> |404| D["Verify resource exists"]
B --> |409| E["Check resource status"]
B --> |500| F["Check server status"]
C --> G["Validate JSON format"]
C --> H["Check parameter types"]
C --> I["Confirm required fields"]
D --> J["Use GET /collections"]
D --> K["Verify collection name"]
D --> L["Check permissions"]
E --> M["Avoid duplicate operations"]
E --> N["Implement concurrency control"]
F --> O["View server logs"]
F --> P["Check system resources"]
F --> Q["Verify storage status"]

Out of memory error: - Monitor memory usage - Adjust batch operation size - Implement memory pressure detection

Insufficient disk space: - Monitor disk usage rate - Implement automatic cleanup mechanism - Configure disk space alerts

Network connection issues: - Implement connection pool management - Add connection timeout settings - Implement automatic reconnection mechanism

Conclusion

GoVector's error handling mechanism is designed following RESTful API best practices, providing clear, consistent error response formats and comprehensive error classification. By understanding the trigger conditions for different status codes, implementing appropriate client retry strategies, and establishing effective log monitoring systems, system stability and user experience can be significantly improved.

Key points: - Always validate request format and parameter validity - Implement reasonable retry mechanism and timeout control - Establish comprehensive log recording and monitoring systems - Distinguish between retryable and non-retryable error types - Provide clear error information and diagnostic suggestions

By following these guidelines, developers can build more robust and reliable vector database applications.