Troubleshooting

​

Authentication Errors

​

”Invalid API key provided”

{"detail": "Invalid API key provided. Set the X-API-Key header to your API key."}

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

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

​

”Your payment has failed”

{"detail": "Your payment has failed. Please pay any unpaid invoices to continue using the API."}

​

Rate Limiting

​

”Rate limit exceeded”

{"detail": "Rate limit exceeded for endpoint /api/v1/marker. 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."}

• 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/marker. 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."}

​

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

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

• 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"}

​

Request Errors

​

”Request not found”

{"detail": "Request not found."}

• 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."}

​

”This request was not made by you”

{"detail": "This request was not made by you."}

​

Webhook Issues

​

Webhook not firing

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)

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

1. Using the wrong webhook secret
2. Request body is being modified by middleware before verification
3. Encoding issues (verify UTF-8 encoding)

​

Processing Issues

​

Conversion returns empty or poor results

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

• 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

1. Using accurate mode on large documents
2. Large file with many pages

• 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"}

​

529 Service Overloaded

​

Next Steps