# 错误

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

来源： https://fileverity.com/zh/docs/errors

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

**错误响应**

```json
{
  "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](mailto:hello@fileverity.com) 获取支持时，请提供该 ID。 |

## 错误类型

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

## 哪些情况应重试

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

仍然无法解决？请发邮件至 [hello@fileverity.com](mailto:hello@fileverity.com)，或使用[联系页面](https://fileverity.com/zh/contact)，并附上请求 ID。

## 错误码

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

| 错误码 | 状态 | 类型 | 消息 |
| --- | --- | --- | --- |
| `invalid_json` | 400 | `invalid_request_error` | 请求体必须是 JSON 对象。 |
| `missing_parameter` | 400 | `invalid_request_error` | 缺少必填参数。 |
| `invalid_parameter` | 400 | `invalid_request_error` | 参数值无效。 |
| `text_too_short` | 400 | `invalid_request_error` | 文本过短，无法评估。请至少发送 100 个词。 |
| `text_too_long` | 413 | `invalid_request_error` | 文本超过 100,000 个字符。请拆分为多个请求。 |
| `unsupported_media_type` | 415 | `invalid_request_error` | 请以 JSON 格式发送请求体，并带上请求头“Content-Type: application/json”。 |
| `unsupported_language` | 400 | `invalid_request_error` | 文本不属于支持的语言。支持的语言为 en、fr、de、es 和 zh。 |
| `file_not_found` | 400 | `invalid_request_error` | 未找到已上传的文件，或文件已过期。请重新上传。 |
| `unsupported_file` | 415 | `invalid_request_error` | 此模型不支持该文件格式。 |
| `file_too_large` | 413 | `invalid_request_error` | 文件超过此模型的大小限制。 |
| `too_many_pixels` | 413 | `invalid_request_error` | 图片超过 4000 万像素。 |
| `too_many_pages` | 413 | `invalid_request_error` | 文档超过 100 页。 |
| `document_too_long` | 413 | `invalid_request_error` | 文档包含的文字过多，无法在一次请求中分析。 |
| `invalid_file` | 422 | `invalid_request_error` | 文件已损坏或无法读取。 |
| `password_required` | 422 | `invalid_request_error` | 文档已加密。请发送其密码以进行分析。 |
| `wrong_password` | 422 | `invalid_request_error` | 文档密码不正确。 |
| `not_examinable` | 422 | `invalid_request_error` | 文档中没有可检查的文字、照片或结构。未扣费。 |
| `missing_api_key` | 401 | `authentication_error` | 未提供 API 密钥。请在请求头“Authorization: Bearer fv_live_...”中发送。 |
| `invalid_api_key` | 401 | `authentication_error` | API 密钥无效或已被撤销。 |
| `insufficient_balance` | 402 | `billing_error` | 您的余额不足以完成此请求。请在控制台中充值。 |
| `spend_limit_reached` | 402 | `billing_error` | 此 API 密钥已达到每月支出上限。请在控制台中提高上限，或等到下个月（UTC）。 |
| `not_found` | 404 | `not_found_error` | 请求的资源不存在。 |
| `model_not_found` | 404 | `not_found_error` | 模型不存在或不可用。 |
| `not_cancelable` | 409 | `conflict_error` | 该分析已无法取消。 |
| `canceled` | 409 | `conflict_error` | 分析已取消，未扣费。 |
| `idempotency_mismatch` | 409 | `conflict_error` | 此 Idempotency-Key 已被用于另一个不同的请求体。 |
| `idempotency_in_progress` | 409 | `conflict_error` | 使用此 Idempotency-Key 的请求仍在处理中。请稍后重试。 |
| `pending_files_limit` | 429 | `rate_limit_error` | 此工作区待处理的上传过多。请分析或删除已上传的文件，或等待文件在最长 24 小时内过期。 |
| `rate_limited` | 429 | `rate_limit_error` | 请求过多。请在 Retry-After 响应头指定的秒数后重试。 |
| `internal_error` | 500 | `api_error` | 请求未能完成。请重试；如果问题持续，请联系技术支持并提供请求 ID。 |
| `analysis_failed` | 502 | `api_error` | 分析未能完成，未扣费。请重试；如果再次失败，请联系技术支持并提供请求 ID。 |
| `service_unavailable` | 503 | `api_error` | 服务暂时不可用或繁忙，未扣费。请在 Retry-After 响应头指定的秒数后重试。 |

## 仅限控制台的错误码

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

| 错误码 | 状态 | 类型 | 消息 |
| --- | --- | --- | --- |
| `session_required` | 401 | `authentication_error` | 请登录后继续。 |
| `forbidden` | 403 | `permission_error` | 您没有执行此操作的权限。 |
| `invite_invalid` | 404 | `not_found_error` | 此邀请无效、已过期或已被使用。 |
| `invite_mismatch` | 403 | `permission_error` | 此邀请发送给了另一个邮箱地址。 |
| `invite_limit` | 409 | `conflict_error` | 此工作区待处理的邀请数量已达上限。请先撤销一个。 |
| `last_owner` | 409 | `conflict_error` | 工作区至少要保留一位所有者。请先指定另一位成员为所有者。 |
| `webhook_limit` | 409 | `conflict_error` | 此工作区的 Webhook 端点数量已达上限。请先删除一个。 |
| `key_limit` | 409 | `conflict_error` | 此工作区的有效 API 密钥数量已达上限。请先撤销一个。 |