API Documentation Beta

Error Codes

This page documents all HTTP status codes and error messages returned by the Enconvert API.

HTTP Status Codes

Code Status Description
200 OK Conversion completed successfully (sync mode).
202 Accepted Batch or async job has been accepted for background processing.
400 Bad Request Invalid parameters, missing required fields, malformed request body, or invalid file content.
401 Unauthorized Missing, invalid, or expired API key or JWT token.
402 Payment Required Monthly conversion limit or storage limit exceeded.
403 Forbidden Feature not available on plan, domain not authorized, endpoint not allowed, or access denied.
404 Not Found Requested resource (job, batch, file, or widget) does not exist.
413 Payload Too Large Uploaded file exceeds the size limit for your subscription plan.
500 Internal Server Error Unexpected error during conversion.
503 Service Unavailable A converter or backend service is unavailable.

Error Response Format

Most error responses follow a standard JSON structure with a detail field:

{
    "detail": "Error message describing the issue"
}
Exception: The 413 Payload Too Large response uses a different format with structured fields instead of detail. See the 413 section below.

400 Bad Request

Returned when the request contains invalid parameters, missing fields, or malformed data.

Input Validation

Message Condition
'url' must be provided Missing or empty url field on URL-based endpoints.
Invalid file format '{ext}' for {endpoint}. Allowed: {list} Uploaded file extension doesn't match the endpoint's accepted formats.
Invalid pdf_options: {error} Malformed JSON in the pdf_options form field.

Batch and Mode Validation

Message Condition
Public keys only support a single URL input Public/dashboard key attempted to send multiple URLs.
output_format=True requires multiple URLs ZIP bundling requested with only one URL.
direct_download not supported for multiple URLs direct_download=true with an array of URLs.
direct_download only works in sync mode direct_download=true combined with async_mode=true.

Auth, Cookies & Headers Validation

Message Condition
'auth' must be an object with 'username' and 'password' auth parameter has wrong structure.
'cookies' must be an array of cookie objects cookies is not an array.
'cookies' array must not exceed 50 entries More than 50 cookies provided.
Cookie at index {i} must be an object Cookie entry is not a dictionary.
Cookie at index {i} must have 'name' and 'value' Cookie missing required fields.
Cookie at index {i} must have 'domain' or 'url' Cookie missing both domain and url.
'headers' must be an object of header name/value pairs headers is not a dictionary.
'headers' must not exceed 20 entries More than 20 custom headers.
Header '{name}' cannot be overridden Attempt to set a blocked header (host, content-length, etc.).
Header '{name}' value must be a string Header value is not a string.
Cannot use both 'auth' and an 'Authorization' header Both auth object and Authorization custom header provided.

Sitemap and Crawl Errors

Message Condition
No URLs found in sitemap: {url} Sitemap parsed but contains no URLs.
Timeout fetching sitemap: {url} Sitemap fetch exceeded 30-second timeout.
Could not fetch sitemap: {url} returned {status} Sitemap URL returned a non-200 HTTP status.
Invalid XML in sitemap: {url} Sitemap XML could not be parsed.
Unrecognized sitemap format at {url}: root element is <{tag}> Sitemap root element is not <urlset> or <sitemapindex>.
No pages discovered on {base_url} Full crawl completed but found zero pages.

Conversion Content Errors

Message Condition
Invalid JSON: {error} JSON file contains invalid JSON syntax.
Invalid YAML: {error} YAML file contains invalid YAML syntax.
Invalid TOML: {error} TOML file contains invalid TOML syntax.
Invalid HTML encoding (expected UTF-8) HTML file is not UTF-8 encoded.
Invalid Markdown encoding (expected UTF-8) Markdown file is not UTF-8 encoded.
JSON must be an array of objects for CSV conversion json-to-csv input is not an array.
JSON array is empty json-to-csv input is an empty array.
CSV file is empty or has no valid rows CSV file has no data rows.
XML structure cannot be converted to CSV XML is not tabular (xml-to-csv).
Turnstile verification failed Cloudflare Turnstile bot challenge failed.
Turnstile token required Widget request without a Turnstile token.

401 Unauthorized

Returned when authentication is missing or invalid.

Message Condition
Authentication required No API key and no JWT token provided in the request.
Invalid API Key format API key is too short or does not start with sk_ or pk_.
Invalid API Key API key hash not found in the database.
API Key revoked API key has been deactivated from the dashboard.
Token has expired JWT access token has expired (1-hour lifetime).
Invalid token JWT is malformed, tampered with, or otherwise invalid.
Refresh token has expired Refresh token has expired (7-day lifetime).
Invalid refresh token Refresh token is malformed or invalid.
Invalid token type Token decoded successfully but is not the expected type (refresh).
No refresh token Widget refresh endpoint called without a refresh_token cookie.

402 Payment Required

Returned when usage limits are exceeded.

Message Condition
Monthly conversion limit reached ({used}/{limit}). Upgrade your plan to continue. Monthly conversion count has reached the plan's limit. Free plan: 100 conversions.
Batch of {N} URLs would exceed your monthly limit. You have {remaining} conversions remaining out of {limit}. Batch request would exceed the remaining monthly quota. The entire batch is rejected upfront.
Storage limit reached. Delete files or upgrade your storage plan to continue. Project storage usage has reached the plan's storage allocation.

403 Forbidden

Returned when access is denied due to key type, domain, plan, or endpoint restrictions.

API Key and Token Restrictions

Message Condition
Private API keys cannot be used from browsers A private key (sk_live_...) was used in a request with a browser Origin header. Use a public key with JWT instead.
Domain {origin} not authorized Request origin does not match any domain in the API key's allowed domains list.
Public API keys can only be used to generate JWT tokens. Please exchange your public key for a JWT token at /v1/auth/token, then use the token for API calls. A public key was used to call a conversion endpoint directly instead of exchanging for a JWT first.
Endpoint '{path}' not allowed for this API key The API key's allowed_endpoints list does not include the requested path.
Endpoint '{path}' not allowed for this token The JWT token's allowed_endpoints list does not include the requested path.
Token issued for different origin Request origin does not match the origin recorded in the JWT (prevents token theft).
Parent origin does not match token X-Parent-Origin header does not match what was validated at token issuance.

Plan Feature Restrictions

Message Condition
Async processing is not available on your current plan. Please upgrade to access this feature. async_mode=true on a plan without async access.
Webhook callbacks is not available on your current plan. Please upgrade to access this feature. callback_url provided on a plan without webhook access.
ZIP output bundling is not available on your current plan. Please upgrade to access this feature. output_format=true on a plan without ZIP output access.
HTTP Basic Auth, cookies, and custom headers is not available on your current plan. Please upgrade to access this feature. auth, cookies, or headers used on a plan without basic auth access.
Batch processing is not available on your current plan. Please upgrade to access this feature. Multiple URLs submitted on a plan with batch_limit of 0.
Batch size {N} exceeds your plan's limit of {M} URLs per batch. Number of URLs exceeds the plan's batch size limit.
Website crawling is not available on your current plan. Please upgrade to access this feature. Website capture endpoint used on a plan with crawl_mode "none" (Free plan).
Full website crawling requires a Pro plan or higher. Your plan supports sitemap-based crawling only. crawl_mode=full requested on a Starter plan that only supports sitemap crawling.

Widget Restrictions

Message Condition
Widget API key has been revoked The widget's linked internal API key has been deactivated.
Domain {origin} is not authorized for this widget Widget embedding domain not in the widget's allowed domains list.
Refresh token does not match widget Refresh token's project ID does not match the widget's project.
Batch status requires a private API key Public or dashboard key attempted to access GET /v1/convert/batch/{batch_id}.
Access denied Attempting to access a resource (job status, file) belonging to a different project.

404 Not Found

Message Condition
Job not found Conversion job ID not found in the database (status polling).
Batch not found Batch ID has no matching activity rows for this project.
File not found Requested file does not exist in storage (download endpoint).
Widget not found Widget ID not found or widget has been deactivated.

413 Payload Too Large

Returned when the uploaded file exceeds the plan's maximum file size.

Different response format: This error uses a structured object instead of the standard detail field. 
{
    "error": "File too large",
    "file_size": 10485760,
    "max_size": 5242880,
    "tier": "free",
    "key_type": "private"
}
Field Description
error Always "File too large".
file_size The size of the uploaded file in bytes.
max_size The maximum allowed file size for your plan in bytes.
tier Your subscription plan slug (e.g., "free", "starter", "pro").
key_type The type of API key used ("private", "public").

File size is checked via the Content-Length request header before the file body is read.

500 Internal Server Error

Message Condition
Conversion failed: {error} An unexpected error occurred during file or URL conversion.

If you encounter persistent 500 errors, the issue is likely with the input file or URL. Try with a different input to isolate the problem.

503 Service Unavailable

Message Condition
Converter not available: {endpoint} The requested converter is not registered or not running.
Converter not available The URL-based converter for the requested endpoint is not available.
Turnstile verification unavailable The Cloudflare Turnstile verification service is unreachable.

These errors are typically transient. Retry the request after a short delay.

Troubleshooting

Authentication Issues

  • Getting 401? Check that your API key is valid and active in the dashboard. If using JWT, ensure the token hasn't expired (1-hour lifetime).
  • Getting 403 about browser usage? You're using a private key (sk_live_...) from client-side code. Switch to a public key with JWT for browser-based requests.
  • Getting 403 about domain? Add your domain to the API key's allowed domains list in the dashboard.

Conversion Issues

  • Getting 400 about file format? Ensure the uploaded file extension matches the endpoint (e.g., .json for json-to-xml, .docx for doc-to-pdf).
  • Getting 413? Your file exceeds the plan's size limit. Check your plan's max file size or upgrade.
  • Getting 402? You've hit your monthly conversion limit or storage limit. Check usage in the dashboard.

Feature Access Issues

  • Getting 403 about plan features? The feature you're trying to use (async, batch, webhooks, etc.) requires a higher plan tier. Check the feature gating table.
← Web Widgets