> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.datalab.to/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting
> Common issues and solutions when using the Datalab API.
This page covers the most common issues you may encounter when using the Datalab API, organized by the error messages you'll see.
## Authentication Errors
### "Invalid API key provided"
```json theme={null}
{"detail": "Invalid API key provided. Set the X-API-Key header to your API key."}
```
**Status:** 401 Unauthorized
**Cause:** The `X-API-Key` header is missing or contains an invalid key.
**Solution:**
1. Check that you're passing the header: `X-API-Key: YOUR_KEY`
2. Verify your key at [datalab.to/app/keys](https://www.datalab.to/app/keys)
3. If using the SDK, set `DATALAB_API_KEY` environment variable or pass `api_key` to the client
4. If the key was recently created, wait a few seconds and retry
### "You need an active, paid subscription"
```json theme={null}
{"detail": "You need an active, paid subscription to use this API."}
```
**Status:** 403 Forbidden
**Cause:** Your team does not have an active subscription or has exhausted free credits.
**Solution:**
1. Sign up for a plan at [datalab.to/pricing](https://www.datalab.to/pricing)
2. If you recently signed up, check that payment was processed successfully
3. Contact [support@datalab.to](mailto:support@datalab.to) if you believe this is in error
### "Your subscription has expired"
```json theme={null}
{"detail": "Your subscription has expired. You may need to re-enable your plan, or pay an unpaid invoice."}
```
**Status:** 403 Forbidden
**Solution:** Check your billing dashboard for unpaid invoices and update your payment method if needed.
### "Your payment has failed"
```json theme={null}
{"detail": "Your payment has failed. Please pay any unpaid invoices to continue using the API."}
```
**Status:** 403 Forbidden
**Solution:** Update your payment method and pay any outstanding invoices at [datalab.to/app/billing](https://www.datalab.to/app/billing).
***
## Rate Limiting
### "Rate limit exceeded"
```json theme={null}
{"detail": "Rate limit exceeded for endpoint /api/v1/convert. You can make 200 requests every 60 seconds. Please try again later, or reach out to support@datalab.to if you need a higher limit."}
```
**Status:** 429 Too Many Requests
**Cause:** You've exceeded the request rate limit for your plan.
**Solution:**
* Wait and retry with exponential backoff (the SDK does this automatically)
* Reduce request frequency or spread requests over time
* For higher limits, contact [support@datalab.to](mailto:support@datalab.to)
```python theme={null}
# The SDK handles retries automatically with exponential backoff.
# For the REST API, implement retry logic:
import time
def request_with_retry(url, headers, max_retries=5):
for attempt in range(max_retries):
response = requests.get(url, headers=headers)
if response.status_code == 429:
wait = min(2 ** attempt * 5, 120)
time.sleep(wait)
continue
return response
raise Exception("Max retries exceeded")
```
### "Concurrency exceeded"
```json theme={null}
{"detail": "Concurrency exceeded for endpoint /api/v1/convert. You can have 400 concurrent requests running at once. Please try again later, or reach out to support@datalab.to if you need a higher limit."}
```
**Status:** 429 Too Many Requests
**Cause:** Too many requests are being processed simultaneously.
**Solution:** Queue your requests and limit the number of concurrent submissions. See [Batch Processing](/docs/recipes/conversion/batch-documents) for patterns.
### "Page rate limit exceeded"
```json theme={null}
{"success": false, "error": "Page rate limit exceeded. Your team has {current_pages} pages in flight and this request adds {page_count} more ({total} total, limit: 5,000). Please wait for some requests to complete before submitting more, or contact support@datalab.to for a higher limit."}
```
**Status:** Not an HTTP error — returned in the result payload with `success: false`
**Cause:** Your team has too many pages being processed concurrently across all requests. The default limit is 5,000 concurrent pages.
**Solution:**
* Wait for in-flight requests to complete before submitting more documents
* If you're polling for results, back off when you see this error and retry after some results return
* If you're using webhooks, wait for completion notifications before submitting more
* For a higher page limit, contact [support@datalab.to](mailto:support@datalab.to)
This limit is **not** enforced at submission time. Your request will be accepted, but the result will come back with `success: false`. Always check the `success` field when retrieving results.
***
## File Errors
### "Invalid file type"
```json theme={null}
{"detail": "Invalid file type. Only PDF files, word documents, spreadsheets, powerpoints, HTML, and PNG, JPG, GIF, TIFF, and WEBP images are accepted."}
```
**Status:** 400 Bad Request
**Cause:** The uploaded file's content type is not supported.
**Solution:**
1. Check [Supported File Types](/docs/common/supportedfiletypes) for the full list
2. Ensure the file extension matches the actual content type
3. If uploading via cURL, the content type may be auto-detected from the extension
### "File size exceeds upload limit"
```json theme={null}
{"detail": "File size exceeds upload limit of 209715200 bytes."}
```
**Status:** 400 Bad Request
**Cause:** The file exceeds the 200 MB size limit.
**Solution:**
* Split large PDFs into smaller files using page ranges
* Use the `page_range` parameter to process specific pages
* See [API Limits](/docs/common/limits) for current limits
### "File too large"
```json theme={null}
{"detail": "File too large. Maximum size: 200MB"}
```
**Status:** 413 Payload Too Large
**Solution:** Same as above — reduce file size or use page ranges.
***
## Request Errors
### "Request not found"
```json theme={null}
{"detail": "Request not found."}
```
**Status:** 404 Not Found
**Cause:** The request ID doesn't exist or has expired.
**Solution:**
* Results are deleted one hour after processing completes — retrieve them promptly
* Verify the request ID is correct
* Submit a new request if the results have expired
### "This resource has expired"
```json theme={null}
{"detail": "This resource has expired."}
```
**Status:** 404 Not Found
**Cause:** The conversion results have been cleaned up (1 hour after completion).
**Solution:** Submit a new conversion request. Consider using [webhooks](/platform/webhooks) to be notified immediately when results are ready.
### "This request was not made by you"
```json theme={null}
{"detail": "This request was not made by you."}
```
**Status:** 403 Forbidden
**Cause:** You're trying to retrieve results for a request made by a different team.
**Solution:** Ensure you're using the same API key that submitted the original request.
***
## Webhook Issues
### Webhook not firing
**Possible causes:**
1. Webhook URL is not configured — set it at [dashboard](https://www.datalab.to/app/settings) or per-request via `webhook_url`
2. Your server is not reachable from Datalab's servers
3. Your server is returning 4xx errors (webhooks are not retried for client errors)
**Debugging steps:**
1. Check your webhook URL is accessible from the internet
2. Verify HTTPS is properly configured (self-signed certificates may cause issues)
3. Check your server logs for incoming requests
4. Use a tool like [webhook.site](https://webhook.site) to test webhook delivery
### Webhook signature verification failing
**Possible causes:**
1. Using the wrong webhook secret
2. Request body is being modified by middleware before verification
3. Encoding issues (verify UTF-8 encoding)
**Solution:** See [Webhook Verification](/platform/webhooks#verifying-webhook-signatures) for the correct verification implementation.
***
## Processing Issues
### Conversion returns empty or poor results
**Possible causes:**
1. Scanned PDF with no OCR layer — use `mode: "accurate"` for better OCR
2. Very complex layout — try `mode: "accurate"`
3. File is corrupted or password-protected
**Solution:**
* Try a different processing mode (fast → balanced → accurate)
* Check the `parse_quality_score` in the response (0-5 scale) to assess output quality
* For scanned documents, `accurate` mode provides the best OCR
### Conversion is slow
**Possible causes:**
1. Using `accurate` mode on large documents
2. Large file with many pages
**Solution:**
* Use `fast` or `balanced` mode for lower latency
* Use `page_range` to process only the pages you need
* Use `max_pages` to limit processing
***
## Server Errors
### "Database error" / "Redis error"
```json theme={null}
{"detail": "Database error"}
```
**Status:** 500 Internal Server Error
**Cause:** Temporary infrastructure issue on Datalab's side.
**Solution:** Wait a moment and retry. If the issue persists, contact [support@datalab.to](mailto:support@datalab.to).
### 529 Service Overloaded
**Cause:** Datalab's servers are temporarily overloaded.
**Solution:** Wait and retry with exponential backoff. The SDK handles this automatically.
***
## Next Steps
Complete HTTP error code reference
Rate limits and file size limits
Set up webhook notifications
SDK with built-in error handling and retries