> ## 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. # Error Codes > HTTP error codes, response formats, and retry guidance. ## Error Response Format All API errors return a JSON response with a `detail` field: ```json theme={null} { "detail": "Error message describing what went wrong" } ``` For validation errors (malformed request body), the response includes field-level details: ```json theme={null} { "detail": [ { "type": "validation_error", "loc": ["body", "field_name"], "msg": "Field validation message", "input": "provided_value" } ] } ``` ## HTTP Error Codes | Code | Type | Retryable | Description | | ---- | ----------------------- | --------- | ------------------------------------------------ | | 400 | `invalid_request_error` | No | Issue with the format or content of your request | | 401 | `authentication_error` | No | Invalid or missing API key | | 403 | `permission_error` | No | API key lacks permission or subscription issue | | 404 | `not_found_error` | No | Requested resource not found or expired | | 413 | `request_too_large` | No | File exceeds the maximum allowed size | | 429 | `rate_limit_error` | **Yes** | Rate limit exceeded — wait and retry | | 500 | `api_error` | **Yes** | Internal server error — wait and retry | | 529 | `overloaded_error` | **Yes** | API temporarily overloaded — wait and retry | ## SDK Exception Mapping The Python SDK maps HTTP errors to specific exception classes: | HTTP Code | SDK Exception | Description | | ---------- | ------------------------ | -------------------------------------------------- | | 400 | `DatalabAPIError` | Check the `response_data` field for details | | 401 | `DatalabAPIError` | Invalid API key | | 403 | `DatalabAPIError` | Subscription or permission issue | | 404 | `DatalabAPIError` | Resource not found or expired | | 413 | `DatalabAPIError` | File too large | | 429 | Auto-retried | SDK retries automatically with exponential backoff | | 500 | Auto-retried | SDK retries automatically | | Timeout | `DatalabTimeoutError` | Request timed out | | File error | `DatalabFileError` | File not found or empty | | Validation | `DatalabValidationError` | Invalid input parameters | ```python theme={null} from datalab_sdk import DatalabClient from datalab_sdk.exceptions import ( DatalabAPIError, DatalabTimeoutError, DatalabFileError, DatalabValidationError, ) client = DatalabClient() try: result = client.convert("document.pdf") except DatalabFileError as e: print(f"File issue: {e}") except DatalabTimeoutError as e: print(f"Timed out: {e}") except DatalabAPIError as e: print(f"API error (HTTP {e.status_code}): {e}") if e.response_data: print(f"Details: {e.response_data}") ``` ## Common Error Messages ### 400 Bad Request ```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."} ``` ```json theme={null} {"detail": "File size exceeds upload limit of 209715200 bytes."} ``` ### 401 Unauthorized ```json theme={null} {"detail": "Invalid API key provided. Set the X-API-Key header to your API key."} ``` ### 403 Forbidden ```json theme={null} {"detail": "You need an active, paid subscription to use this API."} ``` ```json theme={null} {"detail": "Your subscription has expired. You may need to re-enable your plan, or pay an unpaid invoice."} ``` ```json theme={null} {"detail": "Your payment has failed. Please pay any unpaid invoices to continue using the API."} ``` ### 429 Too Many Requests ```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."} ``` ```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."} ``` ### Page Concurrency Limit (returned in results, not as an HTTP error) The page concurrency limit is enforced during processing, not at submission time. Instead of a `429` response, the result will return with `success` set to `false`: ```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."} ``` See [API Limits](/docs/common/limits#page-concurrency-limit) for details. ## Subscription and Access Errors When making API requests, you may encounter 403 errors related to your subscription status: ### No Active Subscription **Error**: `"You need an active, paid subscription to use this API."` This occurs when you don't have an active subscription and have exhausted your free credits. To resolve: * Subscribe to a paid plan in the [dashboard](https://www.datalab.to/app/billing) * New accounts include free credits — verify your email to claim them ### Expired Subscription **Error**: `"Your subscription has expired. You may need to re-enable your plan, or pay an unpaid invoice."` Your subscription has passed its end date and grace period. To resolve: * Renew your subscription in the [dashboard](https://www.datalab.to/app/billing) * Pay any outstanding invoices ### Payment Failed **Error**: `"Your payment has failed. Please pay any unpaid invoices to continue using the API."` A payment for your subscription has failed and you've exceeded the grace period. To resolve: * Update your payment method in the [dashboard](https://www.datalab.to/app/billing) * Pay any unpaid invoices ### Inactive Subscription **Error**: `"Your subscription is not active. You may need to re-enable your plan or pay an unpaid invoice."` Your subscription is canceled or inactive. To resolve: * Reactivate your subscription in the [dashboard](https://www.datalab.to/app/billing) * Subscribe to a new plan ## Next Steps Detailed debugging guide for common issues Per-page pricing, payment failures, and grace periods File size limits, page limits, and rate limiting Python SDK with automatic retries and error handling