> ## Documentation Index
> Fetch the complete documentation index at: https://parse-docs.pantherpulse.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> Handle and troubleshoot API errors

# Error Handling

Comprehensive guide to Finxtract API errors and how to handle them.

## Error Response Format

All errors follow this structure:

```json theme={null}
{
  "error": {
    "code": "error_code",
    "message": "Human-readable message"
  }
}
```

## Authentication Errors (401)

### Invalid API Key

```json theme={null}
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key"
  }
}
```

**Solution**: Verify your API key is correct and hasn't been revoked.

## Validation Errors (400)

### Company Names Mismatch

```json theme={null}
{
  "error": {
    "code": "company_mismatch",
    "message": "Number of company names must match number of files"
  }
}
```

**Solution**: Ensure you submit the same number of company names as files.

### Invalid Content Type

```json theme={null}
{
  "error": {
    "code": "invalid_content_type",
    "message": "Content-Type must be multipart/form-data"
  }
}
```

**Solution**: Set Content-Type header to `multipart/form-data` for file uploads.

### No Files Provided

```json theme={null}
{
  "error": {
    "code": "no_files",
    "message": "No files provided"
  }
}
```

**Solution**: Include at least one file in your request.

### Too Many Files

```json theme={null}
{
  "error": {
    "code": "too_many_files",
    "message": "Max 20 files allowed"
  }
}
```

**Solution**: Upload max 20 files per request. Submit additional batches separately.

### Payload Too Large

```json theme={null}
{
  "error": {
    "code": "payload_too_large",
    "message": "Total size exceeds 4.5 MB"
  }
}
```

**Solution**: Reduce total file size or split into multiple requests.

## Billing Errors (402)

### Monthly Limit Exceeded

```json theme={null}
{
  "error": {
    "code": "limit_exceeded",
    "message": "Monthly limit of 250 pages exceeded. Upgrade your plan."
  }
}
```

**Solution**: Upgrade your plan or wait until next billing cycle.

## Server Errors (5xx)

### Internal Server Error

```json theme={null}
{
  "success": false,
  "error": "internal_error",
  "message": "An unexpected error occurred",
  "code": "internal_error",
  "details": {
    "request_id": "req_xyz789"
  }
}
```

**Solution**: Retry after 5 minutes. Contact support with `request_id` if persists.

## Error Handling Best Practices

### Implement Retry Logic

```python theme={null}
import requests
import time

def upload_with_retry(file_path, max_retries=3):
    for attempt in range(max_retries):
        try:
            with open(file_path, 'rb') as f:
                response = requests.post(
                    'https://lq1qmy4ici.execute-api.ap-southeast-1.amazonaws.com/prod/v1/extract/batch',
                    files={'file': f},
                    data={'user_id': 'ppu_YOUR_USER_ID'},
                    headers={'Authorization': 'Bearer sk_live_YOUR_API_KEY'}
                )
            
            if response.status_code == 429:  # Rate limited
                wait_time = int(response.json()['details']['retry_after'])
                time.sleep(wait_time)
                continue
            
            response.raise_for_status()
            return response.json()
        
        except requests.exceptions.RequestException as e:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # Exponential backoff
            else:
                raise

upload_with_retry('statement.pdf')
```

### Log Error Details

```python theme={null}
import logging

logger = logging.getLogger(__name__)

try:
    response = requests.post(...)
except Exception as e:
    logger.error(f"Failed to upload: {e}", extra={
        'status_code': response.status_code,
        'error_code': response.json()['code'],
        'request_id': response.json()['details']['request_id']
    })
```

### User-Friendly Messages

```python theme={null}
error_messages = {
    'no_files': 'Please upload at least one file',
    'payload_too_large': 'Files are too large. Max 4.5MB total',
    'limit_exceeded': 'Monthly limit reached. Please upgrade',
    'too_many_files': 'Too many files. Max 20 per request'
}

def handle_error(error_code):
    message = error_messages.get(error_code, 'An error occurred. Please try again')
    return message
```

## Contact Support

For persistent errors:

* Email: [support@pantherpulse.ai](mailto:support@pantherpulse.ai)
* Include the request ID from error response
* Provide the exact error message