使用 LlamaParse 时最常见问题的解法。错误码参考表在本页底部。

认证与 API key

每个请求都返回 401 Unauthorized

• 确认你的 API key 有效且未被吊销，可在控制台 查看。
• HTTP API：检查头的格式：Authorization: Bearer llx-...
• Python SDK：确认环境里设了 LLAMA_CLOUD_API_KEY，或在 client 构造时传 api_key="llx-..."。
• TypeScript SDK：确认设了 LLAMA_CLOUD_API_KEY，或在 client 里传 apiKey: "llx-..."。
• 确认你访问的是正确的地域 API 端点 —— 在 NA 创建的 key 用不了 EU API，反之亦然。见地域。
• API key 是 project 级的 —— 确认这把 key 属于你要访问的那个 project。

访问某个资源时返回 403 Forbidden

• 该资源属于另一个组织或另一个 project。
• 你的角色权限可能不够 —— 请与组织管理员确认。
• 你的 project 可能已被管理员停用。
• BYOC 部署请核对 OIDC 配置（token audience、所需 scope、SSL 设置）。

地域与基础 URL

使用 EU 地域或 BYOC 时报错

• EU 地域：把基础 URL 设为 api.cloud.eu.llamaindex.ai。Python SDK 里：LlamaCloud(api_key="llx-...", base_url="api.cloud.eu.llamaindex.ai")。见地域。
• BYOC：把基础 URL 设为你自己的部署端点。确保 OIDC 提供方配置正确（audience、scope、SSL）。
• API key 是分地域的 —— 在 NA 创建的 key 不能用于 EU 端点。

文件上传问题

文件上传失败或超时

• 按各产品的限制核对文件大小。
• 确认文件格式在支持的类型之内。
• 确保文件非空且有文件名。
• 大文件请确保网络稳定 —— 上传不支持断点续传。
• 各端点当前的限额见速率限制。

提示文件类型不支持的错误

• 确认扩展名对应某个支持的格式。
• 带密码保护或 DRM 加密的文件无法处理 —— 上传前请先去掉保护。
• 音频文件（mp3、mp4、wav、m4a、webm）按扩展名自动识别 —— 无需特殊模式。

解析问题

Parse 任务卡住或耗时过长

• 图片很多的复杂文档会更慢，开启 OCR 时尤其。
• 通过 API 或控制台查看任务状态。
• 若用的是 Agentic 或 Agentic Plus 档，可以先试 Cost-effective（每页 3 credit）—— 它同样使用 AI 并产出 markdown，但处理更快。
• 用 target_pages（例如 "1,3,5-8"）只解析你需要的页，而不是整份文档。
• 关掉你不需要的功能（例如图片抽取、专门的图表解析）以加快处理。

解析质量差或内容缺失

• 逐级升档：Cost-effective（3 credit）→ Agentic（10 credit）→ Agentic Plus（45 credit）。每一档使用更高级的 AI 模型。注意：Fast 档（1 credit）只输出空间文本，不输出 markdown。
• 含分栏、复杂页眉或混合结构的文档，加上版面抽取（每页额外 3 credit）。
• 用解析指令（v1 里的 parsing_instruction，或 v2 里的 agentic_options.system_prompt / user_prompt）来引导模型。这只对启用 AI 的档位有效（Fast 无效）。
• 扫描文档要确保图像质量足以让 OCR 使用。v2 里可以用 processing_options.ocr_parameters.languages 指定 OCR 语言。
• 每页超出 64 KB 的内容会被静默截断，每页只处理最大的 35 张图片。若文档触到这些上限，内容会缺失且不报错。见限制。

Parse 任务超时

• 默认情况下，解析任务没有应用层的显式超时 —— 会一直跑到完成。你可以在 v2 的 processing_control.timeouts 里设置超时（上限：基础 2 小时 + 每页 5 分钟）。
• 用 target_pages 减少需要处理的页数。
• 想要更快的处理且仍要 markdown 输出，用 Cost-effective 档而不是 Agentic/Agentic Plus。
• 关掉不必要的功能（图片抽取、图表解析）以缩短时间。

抽取问题

抽取结果为空或不正确

• 检查你的 schema —— 字段名与描述在为模型指引抽取方向，描述要具体、无歧义。
• 若用的是 Fast 或 Balanced 模式，视觉复杂的文档请改试 Multimodal 或 Premium。默认模式是 Premium（准确度最高）。
• 确认文档里确实含有你要抽取的数据。
• 对已解析过的文件，抽取用的是缓存的解析结果 —— 解析质量差，抽取质量也会差。
• schema 的根必须是 type: object 并带 properties。

schema 校验错误

• schema 的根必须是 type: object 并带 properties。
• 不支持默认值（null 除外）。
• 属性总数、嵌套深度、字符数与 schema 原始大小都有上限。完整约束见schema 设计与限制。

分类问题

文档被分错类

• 把规则描述写得具体、详尽（10–2000 字符）。准确度比长度更重要 —— 在描述里同时给出应当匹配与不应当匹配的例子。
• Multimodal 模式（每页 2 credit）用视觉模型看页面截图而不是解析后的文本，当视觉版面是关键时更有帮助。注意：Multimodal 只在 v1 的 classify API 里可用。
• 确保各规则的类型彼此可区分 —— 相互重叠或含糊的描述会带来歧义。

速率限制与节流

遇到 429 Too Many Requests

• 各端点当前的限额见速率限制。
• 速率限制在所有套餐上都相同、且按组织计数，所以多造几把 API key 不会提高限额。
• 在重试逻辑里实现带抖动的指数退避（API 不返回 Retry-After 头）。
• 高负载时用 batch API 批量提交任务，而不是发大量单次请求。

webhook 问题

webhook 没有触发

• webhook URL 必须公网可访问 —— 平台会拦截发往私有/回环 IP 的投递（localhost、192.168.x.x、10.x.x.x 等）。
• 检查你的 webhook 是否为相应事件做了配置。
• webhook 最多尝试 3 次，按指数退避（两次之间分别是 1 秒、2 秒）。
• 你的端点必须在 30 秒内以 2xx 状态码响应，否则该次投递被视为失败。

还需要帮助？

• 查看 LlamaParse 状态页 了解正在进行的事件。
• 当前的服务上限见限制。
• 通过 support@runllama.ai 或你的 LlamaParse 控制台联系支持。

---

错误参考

LlamaParse API 会返回一个 JSON 响应体，其中 detail 字段描述该错误。

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

服务端错误（5xx）的响应里会带一个关联 ID —— 联系支持时请把它一并给出。

配额与计费错误

错误信息	状态	可重试？	处理方式
"You've exceeded the maximum number of credits for your plan."	402	否	升级套餐，或等下一个计费周期。见计费
"No quota left to create a job"	402	否	credit 已用完 —— 请升级套餐
"The total number of files would exceed the maximum allowed..."	402	否	升级套餐以获得更高的文件数上限
"This project has reached its stored-file limit..." / "...its storage limit..."	402	否	该 project 已触及套餐的保留存储上限。请删除文件、改用临时上传，或升级。临时文件不计入。见存储上限
"You've already reached the maximum number of projects..."	429	否，直到套餐上限被调高	已达套餐上限 —— 请升级，或删除不再使用的 project
"You've already reached the maximum number of indexes..."	429	否，直到套餐上限被调高	已达套餐上限 —— 请升级，或删除不再使用的索引
"You've already reached the maximum number of users..."	429	否，直到套餐上限被调高	已达套餐上限 —— 请升级，或移除不再使用的成员
"You've already reached the maximum number of data sources..."	429	否，直到套餐上限被调高	已达套餐上限 —— 请升级，或移除不再使用的数据源
"You've already reached the maximum number of extraction agents..."	429	否，直到套餐上限被调高	已达套餐上限 —— 请升级，或删除不再使用的抽取智能体

文件上传错误

错误信息	状态	可重试？	处理方式
"Uploaded file is empty."	400	否	上传前确认文件有内容
"File must have a filename."	400	否	在 multipart 上传里带上文件名
"file field is required for multipart requests."	400	否	用 multipart/form-data，并把文件放在名为 file 的字段里
"Rate limit exceeded. The file upload limit is ... requests per second."	429	是，等窗口过后并带退避	降低上传速率。见速率限制

Parse 错误

错误信息	状态	可重试？	处理方式
"Either file, input_url, or input_s3_path must be provided."	400	否	提供要解析的文件、URL 或 S3 路径
"File name exceeds the maximum length of ... characters"	400	否	缩短文件名
"Parsing mode ... is not supported."	400	否	改用受支持的解析模式。当前模式见定价
"Vendor multimodal model ... is not supported."	400	否	改用受支持的模型 —— 错误信息会列出合法取值
"Markdown expansion is not available for FAST tier jobs."	400	否	要 markdown 扩展，请用 Cost-effective 档或更高
"Invalid JSON in webhook_configurations: ..."	400	否	修正 webhook 配置里的 JSON 语法
"Access denied to this parse configuration"	403	否	你没有访问这份已保存配置的权限
"Parse job not found"	404	否	任务 ID 无效，或该任务已被删除
"Result not found. Check job status to see if it has completed."	404	是，等任务结束后	任务尚未完成 —— 请先轮询任务状态端点
"Source file not found in storage"	404	否	原始文件已不可用（文件只缓存 48 小时）

任务失败原因 —— 这些出现在任务状态里，而不是 HTTP 响应中：

错误信息	状态	可重试？	处理方式
UNSUPPORTED_FILE_TYPE	File format is not supported	否	查看支持的文档类型
PDF_IS_PROTECTED	The PDF is password-protected, or the spreadsheet is encrypted, password-protected, or rights-managed	否	去掉保护后重新上传
PDF_IS_BROKEN	The PDF is corrupted or malformed	否	试着从源应用重新导出这份 PDF
OFFICE_FILE_IS_BROKEN	The Office document is corrupt or truncated — its content is not a valid file of its claimed type	否	从源应用重新导出该文档，再重新上传
SPREADSHEET_PROCESSING_ERROR	The spreadsheet’s contents could not be read	否	用你的表格应用另存一次，或改成上传 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)	否	重新导出没用 —— 请重新下载或以二进制方式重新传输原始文件，然后再上传
UNSUPPORTED_IMAGE_FORMAT	The image is stored in a format or encoding that could not be decoded	否	把图片转成 PNG 或 JPEG（或导出为 PDF），再重新上传
FILE_IS_EMPTY	The file is 0 bytes, the PDF has no pages, the text file contains only whitespace, or the workbook has no populated cells in its visible sheets	否	上传有内容的文件。电子表格请检查 target_pages 与 max_pages —— 选中为空是另行处理的
NO_DATA_FOUND_IN_FILE	The document was read, but no content could be extracted from it	否	确认文件不是空白页，也不是没开 OCR 的纯图片
INVALID_PAGE_RANGE	target_pages is malformed, or names pages the document does not have	否	对照文档页数检查该范围；注意 v1 从 0 开始编号，v2 从 1 开始
INPUT_S3_ACCESS_DENIED	The object at input_s3_path could not be read	否	确认 bucket 与 key 存在，且已授予 LlamaCloud 读取权限
INPUT_FILE_NOT_FOUND	The input file no longer existed when the job started, usually because it was deleted right after the job was submitted	否	在任务结束前保留该文件，之后重新提交任务
DOCUMENT_TOO_LARGE	The document exceeds a published size or page limit	否	减小文件体积，或使用页范围。见限制
PROCESSING_SIZE_LIMIT_EXCEEDED	The document produced more data than a single job can process, usually a very long or very graphics-dense file	否	拆分文档，或用页范围分段解析
TOO_MANY_PAGES	Document exceeds the maximum page count	否	用页范围解析指定章节
TIMEOUT	Processing exceeded the timeout limit	否	换更快的档、减少页数，或拆成更小的任务
JOB_EXPIRE	The job ran past the job_timeout_in_seconds you set	否	调高超时、减少页数，或拆分文档
DOCUMENT_CONVERSION_TIMEOUT	Converting the document to PDF before parsing took too long (very large or complex spreadsheets, HTML pages, or Office documents)	否	简化或拆分文档，或先导出为 PDF 再上传那份
CONTENT_POLICY_REFUSAL	The document’s content was declined during transcription	否	重试不会改变结果。若你认为判定有误，请联系支持
JOB_CANCELLED	Processing stopped before the job finished	否	重新提交任务

Extract 错误

错误信息	状态	可重试？	处理方式
"schema_validation: ..."	400	否	schema 超出限制。各项约束见schema 设计与限制
"inputs_invalid: ..."	400	否	检查文件 ID、parse 任务 ID 或其他输入参数
"inputs_invalid: Parse job ... is not completed (status: ...)"	400	否	先等解析任务结束，再执行抽取
"File size exceeds ...MB limit." / "File size limit exceeded. Try uploading a smaller file (< ... MB)."	413	否	文件超出 Extract 的体积上限 —— 请减小体积。见限制
"Extraction agent name must have at least some alphanumeric characters."	400	否	改用含字母数字字符的名称
"Cannot delete the default extraction agent."	400	否	默认智能体由系统管理，无法删除
"Access denied to the specified file."	403	否	该文件属于另一个 project
"Extraction agent ... not found or user does not have access."	404	否	检查智能体名称与你的权限
"engine_error: ..."	422	否	抽取引擎失败 —— 请简化 schema 或换一种模式
"llm_refusal"	422	否	大模型拒绝处理该内容 —— 检查是否触及内容政策问题
"Resources exhausted. Please wait for existing jobs to complete."	429	是，等在运行的任务结束后	并发抽取任务过多 —— 稍等后重试

Classify 错误

错误信息	状态	可重试？	处理方式
"File ID ... is not in Project ID ..."	400	否	确认该文件属于所指定的 project
"Parse Job ID ... is not in Project ID ..."	400	否	确认该 parse 任务属于所指定的 project
"Invalid classify configuration parameters for ...: ..."	400	否	按错误详情修正配置参数
"Classify job not found"	404	否	任务 ID 无效或已被删除
"Classify configuration ... not found"	404	否	该已保存配置不存在
"Rate limit exceeded. Maximum 40 request(s) per second allowed."	429	是，等窗口过后并带退避	创建更多分类任务前请先等待
"Classify endpoints are currently unavailable."	503	是，带退避	分类服务暂时不可用 —— 稍后重试

Split 错误

错误信息	状态	可重试？	处理方式
"Only file_id document inputs are supported for split jobs."	400	否	先上传文件，再按文件 ID 引用它
"Unsupported file type: ... Supported file types are ..."	400	否	请使用 PDF、DOCX 或 PPTX
"File size (... MB) exceeds the maximum allowed size of ... MB."	400	否	把文件体积降到上限以内
"Split configuration ... has no categories"	400	否	给该切分配置至少加一个类别
"File ... not found in project ..."	404	否	确认该文件存在于指定 project 中
"Split job not found"	404	否	任务 ID 无效或已被删除

处理错误

• 解析 detail 字段以获取可读的上下文。
• 对 429 与 5xx 错误实现带抖动的指数退避。
• 402 错误请到控制台核对 credit 用量，路径是 Settings → Organization → Usage。
• 任务上的 404 错误，请核实任务 ID，并确认任务未过期。
• 进一步排查前，先看状态页 是否有正在进行的事件。
• 联系 support@runllama.ai 时带上关联 ID（来自 500 响应）。

HTTP 状态码参考

状态	名称	说明
400	Bad Request	请求格式错误或缺少必填参数
401	Unauthorized	缺少或无效的 API key
402	Payment Required	credit 或配额超限
403	Forbidden	对该资源的权限不足
404	Not Found	资源不存在（ID 无效或已删除）
409	Conflict	资源重复或并发修改
413	Payload Too Large	文件超出体积上限。见限制
422	Unprocessable Entity	请求本身合法但数据无效（违反 schema、枚举取值错误）
429	Too Many Requests	超出速率限制。见速率限制
500	Internal Server Error	服务端问题 —— 请以指数退避重试
502	Bad Gateway	后端暂时不可用 —— 稍后重试
503	Service Unavailable	服务过载或正在维护
504	Gateway Timeout	后端超时 —— 稍后重试