Error Handling

All API errors return a consistent JSON structure for predictable client-side handling.

Error Response Structure

ParseSphere APIs return errors in a standardized format:

{
"error_code": "workspace_not_found",
"message": "Workspace not found or access denied",
"details": {
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000"
},
"request_id": "req_abc123def456",
"timestamp": "2025-01-03T12:00:00Z"
}

Response Fields:

• error_code: Machine-readable error code for programmatic handling
• message: Human-readable description safe to display to users
• details: Additional context when available (e.g., which field failed validation)
• request_id: Unique identifier for request tracing and support
• timestamp: When the error occurred (UTC)

HTTP Status Codes

ParseSphere uses standard HTTP status codes to indicate the result of API requests.

Success Codes (2xx)

200 OK: Standard successful request

201 Created: Resource successfully created

202 Accepted: Asynchronous processing has begun

204 No Content: Successful deletion or operation with no response body

Client Error Codes (4xx)

400 Bad Request: Request parameters are malformed or invalid

401 Unauthorized: Missing or invalid authentication credentials

403 Forbidden: Authenticated user lacks permission for the requested operation

404 Not Found: The requested resource doesn't exist

413 Payload Too Large: Uploaded file exceeds size limits

422 Unprocessable Entity: Request is well-formed but fails validation rules

429 Too Many Requests: Rate limit exceeded. Retry after the duration specified in the Retry-After header

Server Error Codes (5xx)

500 Internal Server Error: An internal server error occurred

Document Parsing Errors

File Size Limit (413)

Files exceeding 200 MB are rejected before processing:

{
"error_code": "file_too_large",
"message": "File too large (250.0MB). Maximum allowed: 200MB",
"request_id": "req_abc123def456",
"timestamp": "2025-01-03T12:00:00Z"
}

Solution: Compress or split the document before uploading.

Unsupported File Type (422)

Files with unsupported extensions are rejected:

{
"error_code": "validation_error",
"message": "Unsupported file type: .xyz. Supported formats: pdf, docx, pptx, xlsx, csv, txt, md",
"request_id": "req_abc123def456",
"timestamp": "2025-01-03T12:00:00Z"
}

Supported Formats:

• PDF (.pdf)
• Word (.docx)
• PowerPoint (.pptx)
• Excel (.xlsx)
• CSV (.csv)
• Plain Text (.txt)
• Markdown (.md)

Solution: Convert the document to a supported format.

Parse Not Found (404)

Requesting a parse that doesn't exist or has expired:

{
"error_code": "resource_not_found",
"message": "Parse 550e8400-e29b-41d4-a716-446655440000 not found",
"details": {
  "parse_id": "550e8400-e29b-41d4-a716-446655440000"
},
"request_id": "req_abc123def456",
"timestamp": "2025-01-03T12:00:00Z"
}

Solution: Adjust the session_ttl when creating the parse or save results immediately if you need them longer.

Parse Failed

When a parse job fails, the status endpoint returns details about the failure:

{
"parse_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "failed",
"error": "Failed to extract PDF: Document is corrupted or encrypted",
"created_at": "2025-01-03T12:00:00Z",
"completed_at": "2025-01-03T12:00:05Z"
}

Common Failure Reasons:

• Corrupted files: Document structure is damaged
• Password-protected documents: Encrypted PDFs require decryption
• Invalid file formats: Files disguised with supported extensions
• Processing timeout: Document too complex (exceeds 10 minute limit)

Workspace & File Errors

File Size Limit (413)

Files exceeding 200 MB are rejected:

{
"error_code": "file_too_large",
"message": "File too large (250.0MB). Maximum allowed: 200MB",
"request_id": "req_abc123def456",
"timestamp": "2025-01-03T12:00:00Z"
}

Solution: Split large files into smaller parts or aggregate data before upload.

Unsupported File Format (422)

Only specific formats are supported for workspace files:

{
"error_code": "validation_error",
"message": "Unsupported file type: .json. Supported formats: csv, xlsx, xls for tabular data; pdf, docx, pptx, txt, md for documents",
"request_id": "req_abc123def456",
"timestamp": "2025-01-03T12:00:00Z"
}

Supported Formats:

Tabular Data (for SQL querying):

• CSV (.csv)
• Excel (.xlsx, .xls)

Documents (for RAG search):

• PDF (.pdf)
• Word (.docx)
• PowerPoint (.pptx)
• Plain Text (.txt)
• Markdown (.md)

Workspace Not Found (404)

Accessing a workspace that doesn't exist or you don't have access to:

{
"error_code": "workspace_not_found",
"message": "Workspace not found or access denied",
"details": {
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000"
},
"request_id": "req_abc123def456",
"timestamp": "2025-01-03T12:00:00Z"
}

File Not Found (404)

Accessing a file that doesn't exist in the workspace:

{
"error_code": "resource_not_found",
"message": "File not found in workspace",
"details": {
  "file_id": "880e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000"
},
"request_id": "req_abc123def456",
"timestamp": "2025-01-03T12:00:00Z"
}

No Files in Workspace (400)

Attempting to query a workspace with no completed files:

{
"error_code": "validation_error",
"message": "No completed files found in workspace. Please upload and process files first.",
"request_id": "req_abc123def456",
"timestamp": "2025-01-03T12:00:00Z"
}

Solution: Upload files and wait for processing to complete before querying.

Query Execution Failed (500)

When a natural language query generates invalid SQL or encounters a database error:

{
"error_code": "internal_error",
"message": "An unexpected error occurred. Please try again.",
"request_id": "req_abc123def456",
"timestamp": "2025-01-03T12:00:00Z"
}

Query Timeout (500)

Queries that exceed 60 seconds are terminated:

{
"error_code": "internal_error",
"message": "Query execution timeout after 60 seconds",
"request_id": "req_abc123def456",
"timestamp": "2025-01-03T12:00:00Z"
}

Solution: Simplify your question, add filters to reduce data scope, or query specific files instead of all workspace data.

File Processing Errors

Processing Failed

When file processing fails, the status endpoint returns error details:

{
"id": "880e8400-e29b-41d4-a716-446655440000",
"workspace_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "failed",
"error_message": "Failed to parse CSV: Invalid delimiter or malformed data",
"created_at": "2025-01-03T12:00:00Z",
"completed_at": "2025-01-03T12:00:15Z"
}

Common Causes:

• Malformed CSV: Inconsistent delimiters, unescaped quotes
• Empty file: File contains no data rows
• Encoding issues: Non-UTF-8 encoding
• Excel corruption: Workbook structure is damaged

Exception Types

ParseSphere uses specific exception types for different error categories:

Document Parsing:

• ExtractionError: General extraction failure
• UnsupportedFileError: File type not supported
• FileCorruptedError: Document structure is invalid

Workspace Files:

• DataTransformError: CSV/Excel transformation failed
• SchemaAnalysisError: Unable to analyze file schema
• BlobStorageError: Storage operation failed
• DuckDBConnectionError: Query execution error
• SQLValidationError: Generated SQL failed validation

Error Recovery Strategies

Automatic Retries

Background Task Retries:

• Document parsing: Max 3 retries
• File processing: Max 3 retries
• Retry delay: Exponential backoff

Webhook Delivery Retries:

• Max 3 delivery attempts
• Initial delay: 1 second
• Exponential backoff: delay × 2^attempt

Handling Failed Operations

For Parse Jobs:

1. Check the parse status endpoint for detailed error message
2. Review common failure reasons
3. Fix the issue (e.g., decrypt PDF, repair file)
4. Create a new parse job

For File Processing:

1. Check the file status endpoint for error details
2. Validate CSV format and encoding
3. Verify Excel file isn't corrupted
4. Delete failed file and re-upload

For Queries:

1. Review the query log for execution details
2. Simplify your natural language question
3. Ensure column names match your query intent
4. Try querying fewer files at once

Best Practices

Preventing Errors

Before Uploading Documents for Parsing:

• Check file size is under 200 MB
• Verify file extension matches actual format
• Test that file opens in native application
• Remove password protection from PDFs

Before Uploading Files to Workspaces:

• Check file size is under 200 MB
• Validate CSV has consistent delimiter
• Ensure Excel has data in first sheet
• Use UTF-8 encoding for CSV files

Error Monitoring

Key Metrics to Track:

• Parse success rate by file type
• File processing time and failures
• Query execution time and errors

Getting Help

If you encounter persistent errors:

1. Check Status Endpoints: Always review detailed error messages from status endpoints
2. Note the Request ID: Every error response includes a request_id for tracing
3. Verify Authentication: Ensure API keys are valid and have correct permissions
4. Contact Support: For repeated 500 errors, contact support with the request_id

What's Next?

Learn more about ParseSphere:

• Quick Start - Get started with document parsing
• Authentication - Manage API keys
• Rate Limits - Understand usage limits
• Document Parsing - Deep dive into extraction
• Workspaces & Chat - Natural language queries