datalab-cli 0.1.0

# Errors Reference

Complete reference for error codes, messages, and troubleshooting.

---

## Error Format

### Interactive (TTY)

```
error: Missing API key
hint: Set your API key:
  export DATALAB_API_KEY="your-api-key"
help: https://www.datalab.to/app/keys
```

### JSON (Piped)

```json
{"error":"Missing API key","code":"MISSING_API_KEY"}
```

---

## Error Codes

### Authentication Errors

#### MISSING_API_KEY

| | |
|---|---|
| **Message** | Missing API key. Set DATALAB_API_KEY environment variable |
| **Cause** | The `DATALAB_API_KEY` environment variable is not set |
| **Solution** | Set your API key: `export DATALAB_API_KEY="your-key"` |
| **Help** | [Get API key](https://www.datalab.to/app/keys) |

#### API_ERROR (401)

| | |
|---|---|
| **Message** | API error (401): Unauthorized |
| **Cause** | Invalid or expired API key |
| **Solution** | Verify your API key is correct and active |
| **Help** | Check [API keys dashboard](https://www.datalab.to/app/keys) |

#### API_ERROR (403)

| | |
|---|---|
| **Message** | API error (403): Forbidden |
| **Cause** | API key doesn't have permission for this operation |
| **Solution** | Check your plan supports the requested feature |
| **Help** | Contact [support@datalab.to](mailto:support@datalab.to) |

---

### Input Errors

#### FILE_NOT_FOUND

| | |
|---|---|
| **Message** | File not found: /path/to/file.pdf |
| **Cause** | The specified file doesn't exist or isn't readable |
| **Solution** | Check the file path is correct and you have read permissions |

```bash
# Check file exists
ls -la /path/to/file.pdf

# Check permissions
test -r /path/to/file.pdf && echo "Readable" || echo "Not readable"
```

#### INVALID_INPUT

| | |
|---|---|
| **Message** | Invalid input: [details] |
| **Cause** | Invalid JSON, schema, or parameter value |
| **Solution** | Validate your input JSON |

```bash
# Validate JSON schema
cat schema.json | jq .

# Validate inline JSON
echo '{"fields": [...]}' | jq .
```

#### API_ERROR (413)

| | |
|---|---|
| **Message** | API error (413): Payload too large |
| **Cause** | File exceeds 200 MB size limit |
| **Solution** | Split the file or compress images |

---

### Processing Errors

#### PROCESSING_FAILED

| | |
|---|---|
| **Message** | Processing failed: [details] |
| **Cause** | Document couldn't be processed |
| **Possible causes** | Unsupported format, corrupted file, complex layout |

**Solutions**:
- Try `--mode accurate` for complex documents
- Check file isn't corrupted
- Verify file format is supported (PDF, PNG, JPG, DOCX)

#### TIMEOUT

| | |
|---|---|
| **Message** | Request timed out after X seconds |
| **Cause** | Processing took longer than the timeout |
| **Solutions** | |

```bash
# Increase timeout
datalab convert document.pdf --timeout 600

# Process fewer pages
datalab convert document.pdf --max-pages 50

# Use fast mode
datalab convert document.pdf --mode fast
```

---

### Rate Limiting Errors

#### RATE_LIMITED

| | |
|---|---|
| **Message** | Rate limited. Retry after X seconds |
| **Cause** | Too many requests in a short period |
| **Solution** | Wait and retry, or reduce request rate |

```bash
# Automatic retry after wait
sleep 30 && datalab convert document.pdf
```

**Prevention**:
- Add delays between batch requests
- Use caching to avoid redundant calls
- Use checkpoints for multiple operations

---

### Network Errors

#### NETWORK_ERROR

| | |
|---|---|
| **Message** | Network error: [details] |
| **Cause** | Connection to API failed |
| **Solutions** | |

1. Check internet connection
2. Verify API endpoint is accessible
3. Check for firewall/proxy issues

```bash
# Test connectivity
curl -I https://www.datalab.to/api/v1/health
```

---

### Cache Errors

#### CACHE_ERROR

| | |
|---|---|
| **Message** | Cache error: [details] |
| **Cause** | Error reading/writing cache files |
| **Solutions** | |

```bash
# Check cache directory
ls -la ~/.cache/datalab/

# Clear cache
datalab cache clear

# Check disk space
df -h ~/.cache/datalab/
```

---

### JSON Errors

#### JSON_ERROR

| | |
|---|---|
| **Message** | JSON error: [details] |
| **Cause** | Invalid JSON in request or response |
| **Solutions** | |

```bash
# Validate your JSON
cat schema.json | jq .

# Check for common issues:
# - Missing quotes
# - Trailing commas
# - Unescaped characters
```

---

## Error Handling Patterns

### Bash Script

```bash
#!/bin/bash

result=$(datalab -q convert document.pdf 2>&1)
exit_code=$?

if [ $exit_code -ne 0 ]; then
    error_code=$(echo "$result" | jq -r '.code // "UNKNOWN"')

    case "$error_code" in
        MISSING_API_KEY)
            echo "Please set DATALAB_API_KEY"
            ;;
        FILE_NOT_FOUND)
            echo "File doesn't exist"
            ;;
        RATE_LIMITED)
            echo "Rate limited, waiting..."
            sleep 30
            # Retry
            ;;
        *)
            echo "Error: $(echo "$result" | jq -r '.error')"
            ;;
    esac
    exit 1
fi

echo "$result"
```

### Python

```python
import subprocess
import json
import time

def run_datalab(args, retries=3):
    for attempt in range(retries):
        result = subprocess.run(
            ["datalab", "-q"] + args,
            capture_output=True,
            text=True
        )

        if result.returncode == 0:
            return json.loads(result.stdout)

        try:
            error = json.loads(result.stderr)
            code = error.get("code", "UNKNOWN")

            if code == "RATE_LIMITED":
                time.sleep(30)
                continue
            elif code == "MISSING_API_KEY":
                raise EnvironmentError("DATALAB_API_KEY not set")
            elif code == "FILE_NOT_FOUND":
                raise FileNotFoundError(error.get("error"))
            else:
                raise Exception(f"{code}: {error.get('error')}")
        except json.JSONDecodeError:
            raise Exception(f"Unknown error: {result.stderr}")

    raise Exception("Max retries exceeded")
```

---

## Common Issues

### "Command not found"

```bash
datalab: command not found
```

**Solution**: Add cargo bin to PATH:
```bash
export PATH="$HOME/.cargo/bin:$PATH"
```

### "Permission denied"

```bash
error: File not found: document.pdf
# But file exists!
```

**Solution**: Check file permissions:
```bash
chmod +r document.pdf
```

### Slow Processing

**Solutions**:
1. Use `--mode fast` for simple documents
2. Limit pages with `--max-pages`
3. Use checkpoints for multiple operations
4. Check network latency

### Inconsistent Results

**Solutions**:
1. Use `--skip-cache` for fresh processing
2. Use `--force` to skip API cache
3. Use `--mode accurate` for consistent quality

---

## Getting Help

### Check CLI Help

```bash
datalab --help
datalab convert --help
```

### Check Error Details

```bash
# Verbose error output
datalab convert document.pdf 2>&1 | jq .
```

### Contact Support

- **Email**: [support@datalab.to](mailto:support@datalab.to)
- **Documentation**: [documentation.datalab.to](https://documentation.datalab.to)
- **GitHub Issues**: [github.com/datalab/datalab-cli/issues](https://github.com/datalab/datalab-cli/issues)

---

## See Also

- [Exit Codes](exit-codes.md)
- [Environment Variables](environment.md)
- [Rate Limits](../concepts/rate-limits.md)