跳至正文
语言: zh
菜单

Fileverity API 文档

错误

Fileverity API 的错误格式、HTTP 状态码和完整的错误码表，并说明哪些错误应当重试。

查看 Markdown更新于 2026-11-04

错误使用标准的 HTTP 状态码，响应体为带有稳定 code 的 JSON。请以 code 而不是 message 作为判断依据：消息内容可能会变化。

{  "error": {    "type": "invalid_request_error",    "code": "invalid_parameter",    "message": "Unrecognized parameter: files.",    "param": "files",    "request_id": "req_4mQ9cX2vB7nP1sK8tL3wR6yZ"  }}
字段说明
error.type错误类别。每种类型对应一类 HTTP 状态码，见下文列表。
error.code稳定且机器可读的标识符。
error.message供人阅读的说明，可能会指明相关的字段或限制。
error.param引发错误的请求字段，或为 null。
error.request_id本次请求的 ID，同时也在 x-request-id 响应头中。联系 hello@fileverity.com 获取支持时，请提供该 ID。

错误类型

类型状态含义
invalid_request_error400, 413, 415, 422请求格式有误或超出限制。请修正请求；原样重试仍会失败。
authentication_error401缺少 API 密钥或 API 密钥无效。
billing_error402余额或支出上限导致请求被拒绝。请充值或提高上限。
not_found_error404资源不存在、已过期，或属于其他工作区。
conflict_error409请求与当前状态冲突。
rate_limit_error429请求过多，或待处理的上传过多。对于 rate_limited，请等待 retry-after 秒。pending_files_limit 不带 retry-after：请使用或删除这些文件，或等待文件过期。
api_error500, 502, 503我们这边出现问题，或资源繁忙。这些请求未扣费。请采用退避策略重试。service_unavailable 会带有 retry-after 响应头。

哪些情况应重试

  • 重试 rate_limited（等待 retry-after 秒后）以及 internal_error、analysis_failed 和 service_unavailable（采用指数退避；对 service_unavailable，先等待 retry-after 秒）。请发送相同的 Idempotency-Key，确保重试不会导致重复执行。参见幂等性。
  • 等待后重试 idempotency_in_progress。
  • 不要重试其他 4xx 错误，除非您已修改请求或账号状态。
  • 以错误结束的检测不会扣费。

仍然无法解决？请发邮件至 hello@fileverity.com，或使用联系页面，并附上请求 ID。

错误码

此表由 API 自身的错误定义生成。

错误码状态类型消息
invalid_json400invalid_request_error请求体必须是 JSON 对象。
missing_parameter400invalid_request_error缺少必填参数。
invalid_parameter400invalid_request_error参数值无效。
text_too_short400invalid_request_error文本过短，无法评估。请至少发送 100 个词。
text_too_long413invalid_request_error文本超过 100,000 个字符。请拆分为多个请求。
unsupported_media_type415invalid_request_error请以 JSON 格式发送请求体，并带上请求头“Content-Type: application/json”。
unsupported_language400invalid_request_error文本不属于支持的语言。支持的语言为 en、fr、de、es 和 zh。
file_not_found400invalid_request_error未找到已上传的文件，或文件已过期。请重新上传。
unsupported_file415invalid_request_error此模型不支持该文件格式。
file_too_large413invalid_request_error文件超过此模型的大小限制。
too_many_pixels413invalid_request_error图片超过 4000 万像素。
too_many_pages413invalid_request_error文档超过 100 页。
document_too_long413invalid_request_error文档包含的文字过多，无法在一次请求中分析。
invalid_file422invalid_request_error文件已损坏或无法读取。
password_required422invalid_request_error文档已加密。请发送其密码以进行分析。
wrong_password422invalid_request_error文档密码不正确。
not_examinable422invalid_request_error文档中没有可检查的文字、照片或结构。未扣费。
missing_api_key401authentication_error未提供 API 密钥。请在请求头“Authorization: Bearer fv_live_...”中发送。
invalid_api_key401authentication_errorAPI 密钥无效或已被撤销。
insufficient_balance402billing_error您的余额不足以完成此请求。请在控制台中充值。
spend_limit_reached402billing_error此 API 密钥已达到每月支出上限。请在控制台中提高上限，或等到下个月（UTC）。
not_found404not_found_error请求的资源不存在。
model_not_found404not_found_error模型不存在或不可用。
not_cancelable409conflict_error该分析已无法取消。
canceled409conflict_error分析已取消，未扣费。
idempotency_mismatch409conflict_error此 Idempotency-Key 已被用于另一个不同的请求体。
idempotency_in_progress409conflict_error使用此 Idempotency-Key 的请求仍在处理中。请稍后重试。
pending_files_limit429rate_limit_error此工作区待处理的上传过多。请分析或删除已上传的文件，或等待文件在最长 24 小时内过期。
rate_limited429rate_limit_error请求过多。请在 Retry-After 响应头指定的秒数后重试。
internal_error500api_error请求未能完成。请重试；如果问题持续，请联系技术支持并提供请求 ID。
analysis_failed502api_error分析未能完成，未扣费。请重试；如果再次失败，请联系技术支持并提供请求 ID。
service_unavailable503api_error服务暂时不可用或繁忙，未扣费。请在 Retry-After 响应头指定的秒数后重试。

仅限控制台的错误码

这些错误码由控制台自身的接口返回，这些接口依赖您的登录会话。使用 API 密钥发出的请求不会返回它们。

错误码状态类型消息
session_required401authentication_error请登录后继续。
forbidden403permission_error您没有执行此操作的权限。
invite_invalid404not_found_error此邀请无效、已过期或已被使用。
invite_mismatch403permission_error此邀请发送给了另一个邮箱地址。
invite_limit409conflict_error此工作区待处理的邀请数量已达上限。请先撤销一个。
last_owner409conflict_error工作区至少要保留一位所有者。请先指定另一位成员为所有者。
webhook_limit409conflict_error此工作区的 Webhook 端点数量已达上限。请先删除一个。
key_limit409conflict_error此工作区的有效 API 密钥数量已达上限。请先撤销一个。