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”

{"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
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”

{"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
2. If you recently signed up, check that payment was processed successfully
3. Contact [e-mail] if you believe this is in error

”Your subscription has expired”

{"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”

{"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.

---

Rate Limiting

”Rate limit exceeded”

{"detail": "Rate limit exceeded for endpoint /api/v1/convert. You can make 400 requests every 60 seconds. Please try again later, or reach out to [e-mail] 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 [e-mail]

# 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”

{"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 [e-mail] 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 for patterns.

”Page rate limit exceeded”

{"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 [e-mail] 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 [e-mail]

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”

{"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 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”

{"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 for current limits

”File too large”

{"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”

{"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”

{"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 to be notified immediately when results are ready.

”This request was not made by you”

{"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 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 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 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”

{"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 [e-mail].

529 Service Overloaded

Cause: Datalab’s servers are temporarily overloaded.

Solution: Wait and retry with exponential backoff. The SDK handles this automatically.

---

Next Steps

Error Codes

Complete HTTP error code reference

API Limits

Rate limits and file size limits

Webhooks

Set up webhook notifications

SDK Reference

SDK with built-in error handling and retries