Troubleshooting & Error Codes

Solutions for the most common issues encountered when using LlamaParse. Error code reference tables are at the bottom of this page.

Authentication & API Keys

401 Unauthorized on every request

• Verify your API key is valid and not revoked in the dashboard.
• HTTP API: Check the header format: Authorization: Bearer llx-...
• Python SDK: Ensure LLAMA_CLOUD_API_KEY is set in your environment, or pass api_key="llx-..." to the client constructor.
• TypeScript SDK: Ensure LLAMA_CLOUD_API_KEY is set, or pass apiKey: "llx-..." to the client.
• Verify you’re hitting the correct regional API endpoint — a key created in NA won’t work against the EU API, and vice versa. See Regions.
• API keys are project-scoped — confirm the key belongs to the project you’re targeting.

403 Forbidden when accessing a resource

• The resource belongs to a different organization or project.
• Your role may not have sufficient permissions — check with your org admin.
• Your project may have been disabled by an administrator.
• For BYOC deployments, verify your OIDC configuration (token audience, required scopes, SSL settings).

Region & Base URL

Getting errors when using the EU region or BYOC

• EU region: Set the base URL to api.cloud.eu.llamaindex.ai. In the Python SDK: LlamaCloud(api_key="llx-...", base_url="api.cloud.eu.llamaindex.ai"). See Regions.
• BYOC: Set the base URL to your custom deployment endpoint. Ensure your OIDC provider is configured correctly (audience, scopes, SSL).
• API keys are region-specific — a key created in NA cannot be used with the EU endpoint.

File Upload Issues

File upload fails or times out

• Check file size against product-specific limits.
• Verify the file format is in the supported types.
• Ensure the file is not empty and has a filename.
• For large files, ensure a stable network connection — uploads are not resumable.
• Check Rate Limits for current per-endpoint limits.

File type not supported error

• Verify the file extension matches a supported format.
• Password-protected or DRM-encrypted files cannot be processed — remove protection before uploading.
• Audio files (mp3, mp4, wav, m4a, webm) are auto-detected by extension — no special mode is needed.

Parsing Problems

Parse job is stuck or taking too long

• Complex documents with many images take longer, especially with OCR.
• Check job status via the API or dashboard.
• If using Agentic or Agentic Plus tiers, try Cost-effective (3 credits/page) first — it still uses AI and produces markdown, but processes faster.
• Use target_pages (e.g., "1,3,5-8") to parse only the pages you need instead of the full document.
• Disable features you don’t need (e.g., image extraction, specialized chart parsing) to speed up processing.

Poor parsing quality or missing content

• Upgrade tier gradually: Cost-effective (3 credits) → Agentic (10 credits) → Agentic Plus (45 credits). Each tier uses more sophisticated AI models. Note: Fast tier (1 credit) outputs spatial text only, not markdown.
• Add layout extraction (+3 credits/page) for documents with columns, complex headers, or mixed structure.
• Use parsing instructions (parsing_instruction in v1, or agentic_options.system_prompt / user_prompt in v2) to guide the model. This only applies to AI-powered tiers (not Fast).
• For scanned documents, ensure image quality is sufficient for OCR. You can specify OCR language via processing_options.ocr_parameters.languages in v2.
• Content beyond 64 KB per page is silently truncated. Only the 35 largest images per page are processed. If your document hits these limits, content will be missing without an error. See Limitations.

Parse job timed out

• By default, parse jobs have no explicit application-level timeout — they run until completion. You can set timeouts via processing_control.timeouts in v2 (max: 30 min base + 5 min per page).
• Use target_pages to reduce the number of pages processed.
• Use Cost-effective tier instead of Agentic/Agentic Plus for faster processing with markdown output.
• Disable unnecessary features (image extraction, chart parsing) to reduce processing time.

Extraction Issues

Extraction returns empty or incorrect results

• Review your schema — field names and descriptions guide the model’s extraction. Be specific and unambiguous in descriptions.
• Verify your extraction target (PER_DOC, PER_PAGE, PER_TABLE_ROW) matches your document structure.
• If using Fast or Balanced mode, try Multimodal or Premium for visually complex documents. The default mode is Premium (highest accuracy).
• Check that the document actually contains the data you’re trying to extract.
• For pre-parsed files, extraction uses the cached parse result — if the parse quality was poor, extraction will be too.
• The root of your schema must be type: object with properties.

Schema validation error

• The schema root must be type: object with properties.
• Default values (other than null) are not supported.
• There are limits on total properties, nesting depth, character counts, and raw schema size. See Schema design and restrictions for the full list of constraints.

Classification Issues

Documents are misclassified

• Write specific, detailed rule descriptions (10-2000 characters). Precision matters more than length — include examples of what should and shouldn’t match within the description.
• Multimodal mode (2 credits/page) uses vision models on page screenshots instead of parsed text, which helps when visual layout matters. Note: Multimodal is only available in the v1 classify API.
• Ensure rule types are distinct — overlapping or vague descriptions cause ambiguity.

Rate Limits & Throttling

Getting 429 Too Many Requests

• See Rate Limits for current per-endpoint limits.
• Free tier organizations have a lower rate limit of 20 requests per minute.
• Implement exponential backoff with jitter in your retry logic (the API does not return Retry-After headers).
• For high-volume workloads, use the batch API to submit jobs in bulk rather than making many individual requests.

Webhook Issues

Webhooks are not firing

• Webhook URLs must be publicly accessible — the platform blocks delivery to private/loopback IPs (localhost, 192.168.x.x, 10.x.x.x, etc.).
• Check that the correct events are configured for your webhook.
• Webhooks retry up to 3 times with exponential backoff (1s, then 2s delays between attempts).
• Your endpoint must respond within 30 seconds with a 2xx status code, or the delivery is treated as failed.

Still Need Help?

• Check the LlamaParse Status Page for ongoing incidents.
• Review Limitations for current service limits.
• Contact support at support@runllama.ai or through your LlamaParse dashboard.

---

Error Reference

LlamaParse APIs return a JSON body with a detail field describing the error.

{
  "detail": "Human-readable error message"
}

For server errors (5xx), the response includes a correlation ID — include this when contacting support.

Quota & Billing Errors

Error Message	Status	Resolution
"You've exceeded the maximum number of credits for your plan."	402	Upgrade your plan or wait for the next billing cycle. See Billing
"No quota left to create a job"	402	Credits exhausted — upgrade your plan
"The total number of files would exceed the maximum allowed..."	402	Upgrade your plan for a higher file limit
"This project has reached its stored-file limit..." / "...its storage limit..."	402	Project is at its plan’s retained-storage cap. Delete files, upload ephemerally, or upgrade. Ephemeral files are exempt. See Storage limits
"You've already reached the maximum number of projects..."	429	Plan limit reached — upgrade or delete unused projects
"You've already reached the maximum number of indexes..."	429	Plan limit reached — upgrade or delete unused indexes
"You've already reached the maximum number of users..."	429	Plan limit reached — upgrade or remove unused members
"You've already reached the maximum number of data sources..."	429	Plan limit reached — upgrade or remove unused data sources
"You've already reached the maximum number of extraction agents..."	429	Plan limit reached — upgrade or delete unused agents

File Upload Errors

Error Message	Status	Resolution
"Uploaded file is empty."	400	Ensure the file has content before uploading
"File must have a filename."	400	Include a filename in the multipart upload
"file field is required for multipart requests."	400	Send the file in a field named file using multipart/form-data
"Rate limit exceeded. The file upload limit is ... requests per second."	429	Slow down upload rate. See Rate Limits

Parse Errors

Error Message	Status	Resolution
"Either file, input_url, or input_s3_path must be provided."	400	Provide a file, URL, or S3 path to parse
"File name exceeds the maximum length of ... characters"	400	Shorten the filename
"Parsing mode ... is not supported."	400	Use a supported parse mode. See Pricing for current modes
"Vendor multimodal model ... is not supported."	400	Use a supported model — the error message lists the valid options
"Markdown expansion is not available for FAST tier jobs."	400	Use Cost-effective tier or higher for markdown expansion
"Invalid JSON in webhook_configurations: ..."	400	Fix the JSON syntax in your webhook configuration
"Access denied to this parse configuration"	403	You don’t have access to this saved configuration
"Parse job not found"	404	The job ID is invalid or the job has been deleted
"Result not found. Check job status to see if it has completed."	404	The job hasn’t finished yet — poll the job status endpoint first
"Source file not found in storage"	404	The original file is no longer available (files are cached for 48 hours)

Job failure reasons — these appear in job status rather than HTTP responses:

Error Type	Meaning	Resolution
UNSUPPORTED_FILE_TYPE	File format is not supported	Check Supported Document Types
PDF_IS_PROTECTED	The PDF is password-protected	Remove password protection and re-upload
PDF_IS_BROKEN	The PDF is corrupted or malformed	Try re-exporting the PDF from the source application
OFFICE_FILE_IS_BROKEN	The Office document is corrupt or truncated — its content is not a valid file of its claimed type	Re-export the document from the source application, then re-upload it
SPREADSHEET_PROCESSING_ERROR	The spreadsheet’s contents could not be read	Re-save the file from your spreadsheet application, or upload it as CSV
FILE_IS_CORRUPT	The file’s binary content was destroyed before upload (e.g. a text-mode transfer or encoding conversion replaced its bytes)	Re-exporting won’t help — re-download or re-transfer the original file in binary mode, then re-upload
UNSUPPORTED_IMAGE_FORMAT	The image is stored in a format or encoding that could not be decoded	Convert the image to PNG or JPEG (or export it to PDF), then re-upload
FILE_IS_EMPTY	The uploaded file is 0 bytes	Check the file you uploaded — nothing was received to parse
NO_DATA_FOUND_IN_FILE	The document was read, but no content could be extracted from it	Verify the file isn’t blank or image-only without OCR
INVALID_PAGE_RANGE	target_pages is malformed, or names pages the document does not have	Check the range against the document’s page count, and note that v1 numbers pages from 0 while v2 numbers them from 1
INPUT_S3_ACCESS_DENIED	The object at input_s3_path could not be read	Check the bucket and key exist, and that LlamaCloud is granted read access to them
DOCUMENT_TOO_LARGE	The document exceeds a published size or page limit	Reduce file size or use page ranges. See Limitations
PROCESSING_SIZE_LIMIT_EXCEEDED	The document produced more data than a single job can process, usually a very long or very graphics-dense file	Split the document, or use page ranges to parse it in sections
TOO_MANY_PAGES	Document exceeds the maximum page count	Use page ranges to parse specific sections
TIMEOUT	Processing exceeded the timeout limit	Use a faster tier, reduce page count, or split into smaller jobs
JOB_EXPIRE	The job ran past the job_timeout_in_seconds you set	Raise the timeout, reduce the page count, or split the document
DOCUMENT_CONVERSION_TIMEOUT	Converting the document to PDF before parsing took too long (very large or complex spreadsheets, HTML pages, or Office documents)	Simplify or split the document, or export it to PDF and upload that instead
CONTENT_POLICY_REFUSAL	The document’s content was declined during transcription	Retrying will not change the outcome. Contact support if you believe this is wrong
JOB_CANCELLED	Processing stopped before the job finished	Submit the job again

Extract Errors

Error Message	Status	Resolution
"schema_validation: ..."	400	Schema exceeds limits. See Schema design and restrictions for constraints
"inputs_invalid: ..."	400	Check file ID, parse job ID, or other input parameters
"inputs_invalid: Parse job ... is not completed (status: ...)"	400	Wait for the parse job to complete before running extraction
"File size exceeds ...MB limit."	413	File exceeds the Extract size limit — reduce file size. See Limitations
"Extraction agent name must have at least some alphanumeric characters."	400	Use a name with alphanumeric characters
"Cannot delete the default extraction agent."	400	Default agents are system-managed and cannot be deleted
"Access denied to the specified file."	403	The file belongs to a different project
"Extraction agent ... not found or user does not have access."	404	Check the agent name and your permissions
"engine_error: ..."	422	Extraction engine failure — simplify your schema or try a different mode
"llm_refusal"	422	The LLM refused to process the content — check for content policy issues
"Resources exhausted. Please wait for existing jobs to complete."	429	Too many concurrent extraction jobs — wait and retry

Classify Errors

Error Message	Status	Resolution
"File ID ... is not in Project ID ..."	400	Ensure the file belongs to the specified project
"Parse Job ID ... is not in Project ID ..."	400	Ensure the parse job belongs to the specified project
"Invalid classify configuration parameters for ...: ..."	400	Fix the configuration parameters per the error details
"Classify job not found"	404	The job ID is invalid or has been deleted
"Classify configuration ... not found"	404	The saved configuration doesn’t exist
"Rate limit exceeded. Maximum 40 classify job creations per second."	429	Wait before creating more classify jobs
"Classify endpoints are currently unavailable."	503	The classify service is temporarily down — retry later

Split Errors

Error Message	Status	Resolution
"Only file_id document inputs are supported for split jobs."	400	Upload the file first, then reference it by file ID
"Unsupported file type: ... Supported file types are ..."	400	Use PDF, DOC, DOCX, PPT, or PPTX
"File size (... MB) exceeds the maximum allowed size of ... MB."	400	Reduce file size to under the limit
"Split configuration ... has no categories"	400	Add at least one category to the split configuration
"File ... not found in project ..."	404	Ensure the file exists in the specified project
"Split job not found"	404	The job ID is invalid or has been deleted

Handling Errors

• Parse the detail field for human-readable context.
• Implement exponential backoff with jitter for 429 and 5xx errors.
• For 402 errors, check your credit usage in the dashboard under Settings > Billing > Usage.
• For 404 errors on jobs, verify the job ID and check that the job hasn’t expired.
• Check the Status Page for ongoing incidents before debugging further.
• Include the correlation ID (from 500 responses) when contacting support@runllama.ai.

HTTP Status Code Reference

Status	Name	Description
400	Bad Request	Malformed request or missing required parameters
401	Unauthorized	Missing or invalid API key
402	Payment Required	Credit or quota limit exceeded
403	Forbidden	Insufficient permissions for this resource
404	Not Found	Resource doesn’t exist (invalid ID or deleted)
409	Conflict	Duplicate resource or concurrent modification
413	Payload Too Large	File exceeds size limit. See Limitations
422	Unprocessable Entity	Valid request but invalid data (schema violations, bad enum values)
429	Too Many Requests	Rate limit exceeded. See Rate Limits
500	Internal Server Error	Server issue — retry with exponential backoff
502	Bad Gateway	Backend temporarily unavailable — retry shortly
503	Service Unavailable	Service overloaded or under maintenance
504	Gateway Timeout	Backend timed out — retry shortly