Skip to main content
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 support@datalab.to 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 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
# 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 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 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 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
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 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

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