# Lỗi

> Định dạng lỗi của Fileverity API, các mã trạng thái HTTP và bảng đầy đủ các mã lỗi, kèm hướng dẫn nên thử lại những lỗi nào.

Nguồn: https://fileverity.com/vi/docs/errors

Lỗi dùng mã trạng thái HTTP chuẩn và nội dung JSON có `code` ổn định. Hãy phân nhánh xử lý theo `code`, không theo `message`: nội dung thông báo có thể thay đổi.

**Phản hồi lỗi**

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Unrecognized parameter: files.",
    "param": "files",
    "request_id": "req_4mQ9cX2vB7nP1sK8tL3wR6yZ"
  }
}
```

| Trường | Mô tả |
| --- | --- |
| `error.type` | Phân loại lỗi. Mỗi type tương ứng với một nhóm mã trạng thái HTTP, được liệt kê bên dưới. |
| `error.code` | Mã định danh ổn định, dạng máy đọc được. |
| `error.message` | Lời giải thích dành cho người đọc. Có thể nêu tên trường hoặc giới hạn liên quan. |
| `error.param` | Trường của yêu cầu gây ra lỗi, hoặc `null`. |
| `error.request_id` | Mã của yêu cầu này, cũng có trong header phản hồi `x-request-id`. Hãy cung cấp mã này khi bạn liên hệ hỗ trợ qua [hello@fileverity.com](mailto:hello@fileverity.com). |

## Các loại lỗi

| Kiểu | Trạng thái | Ý nghĩa |
| --- | --- | --- |
| `invalid_request_error` | 400, 413, 415, 422 | Yêu cầu sai định dạng hoặc vi phạm một giới hạn. Hãy sửa yêu cầu; thử lại mà không thay đổi sẽ lại thất bại. |
| `authentication_error` | 401 | Khóa API bị thiếu hoặc không hợp lệ. |
| `billing_error` | 402 | Số dư hoặc hạn mức chi tiêu khiến yêu cầu bị dừng. Hãy nạp tiền hoặc tăng hạn mức. |
| `not_found_error` | 404 | Tài nguyên không tồn tại, đã hết hạn hoặc thuộc về một không gian làm việc khác. |
| `conflict_error` | 409 | Yêu cầu xung đột với trạng thái hiện tại. |
| `rate_limit_error` | 429 | Quá nhiều yêu cầu hoặc quá nhiều tệp tải lên đang chờ. Với `rate_limited`, hãy chờ số giây trong `retry-after`. `pending_files_limit` không kèm `retry-after`: hãy dùng, xóa hoặc chờ các tệp hết hạn. |
| `api_error` | 500, 502, 503 | Sự cố từ phía chúng tôi hoặc công suất xử lý đang bận. Các yêu cầu này không bị tính phí. Hãy thử lại với backoff (giãn cách tăng dần giữa các lần thử). `service_unavailable` có kèm header `retry-after`. |

## Nên thử lại những gì

- **Thử lại** `rate_limited` sau số giây trong `retry-after`, và thử lại `internal_error`, `analysis_failed` và `service_unavailable` với exponential backoff (với `service_unavailable`, bắt đầu bằng số giây trong `retry-after`). Gửi cùng `Idempotency-Key` để một lần thử lại không thể chạy hai lần. Xem [Idempotency](https://fileverity.com/vi/docs/idempotency.md).
- **Chờ rồi thử lại** `idempotency_in_progress`.
- **Không thử lại** các lỗi `4xx` khác cho đến khi bạn thay đổi yêu cầu hoặc trạng thái tài khoản.
- Lượt kiểm tra kết thúc bằng lỗi không bị tính phí.

Vẫn chưa giải quyết được? Hãy gửi email tới [hello@fileverity.com](mailto:hello@fileverity.com) hoặc dùng [trang liên hệ](https://fileverity.com/vi/lien-he), kèm mã yêu cầu.

## Mã lỗi

Bảng này được tạo từ chính các định nghĩa lỗi của API.

| Mã lỗi | Trạng thái | Kiểu | Thông báo |
| --- | --- | --- | --- |
| `invalid_json` | 400 | `invalid_request_error` | Nội dung yêu cầu phải là một đối tượng JSON. |
| `missing_parameter` | 400 | `invalid_request_error` | Thiếu một tham số bắt buộc. |
| `invalid_parameter` | 400 | `invalid_request_error` | Một tham số có giá trị không hợp lệ. |
| `text_too_short` | 400 | `invalid_request_error` | Văn bản quá ngắn để đánh giá. Hãy gửi ít nhất 100 từ. |
| `text_too_long` | 413 | `invalid_request_error` | Văn bản vượt quá 100.000 ký tự. Hãy chia thành nhiều yêu cầu. |
| `unsupported_media_type` | 415 | `invalid_request_error` | Hãy gửi nội dung yêu cầu dưới dạng JSON kèm header "Content-Type: application/json". |
| `unsupported_language` | 400 | `invalid_request_error` | Văn bản không thuộc ngôn ngữ được hỗ trợ. Các ngôn ngữ được hỗ trợ là en, fr, de, es và zh. |
| `file_not_found` | 400 | `invalid_request_error` | Không tìm thấy tệp đã tải lên hoặc tệp đã hết hạn. Hãy tải tệp lên lại. |
| `unsupported_file` | 415 | `invalid_request_error` | Định dạng tệp không được hỗ trợ cho mô hình này. |
| `file_too_large` | 413 | `invalid_request_error` | Tệp vượt quá giới hạn dung lượng của mô hình này. |
| `too_many_pixels` | 413 | `invalid_request_error` | Ảnh vượt quá 40 megapixel. |
| `too_many_pages` | 413 | `invalid_request_error` | Tài liệu vượt quá 100 trang. |
| `document_too_long` | 413 | `invalid_request_error` | Tài liệu có quá nhiều văn bản để phân tích trong một yêu cầu. |
| `invalid_file` | 422 | `invalid_request_error` | Tệp bị hỏng hoặc không đọc được. |
| `password_required` | 422 | `invalid_request_error` | Tài liệu đã được mã hóa. Hãy gửi mật khẩu của tài liệu để phân tích. |
| `wrong_password` | 422 | `invalid_request_error` | Mật khẩu của tài liệu không đúng. |
| `not_examinable` | 422 | `invalid_request_error` | Tài liệu không có văn bản, ảnh hay cấu trúc nào có thể kiểm tra. Bạn không bị tính phí. |
| `missing_api_key` | 401 | `authentication_error` | Chưa cung cấp khóa API. Hãy gửi khóa trong header "Authorization: Bearer fv_live_...". |
| `invalid_api_key` | 401 | `authentication_error` | Khóa API không hợp lệ hoặc đã bị thu hồi. |
| `insufficient_balance` | 402 | `billing_error` | Số dư của bạn không đủ cho yêu cầu này. Hãy nạp tiền vào số dư trong Console. |
| `spend_limit_reached` | 402 | `billing_error` | Khóa API này đã đạt hạn mức chi tiêu hằng tháng. Hãy tăng hạn mức trong Console hoặc chờ đến tháng sau (UTC). |
| `not_found` | 404 | `not_found_error` | Tài nguyên được yêu cầu không tồn tại. |
| `model_not_found` | 404 | `not_found_error` | Mô hình không tồn tại hoặc không khả dụng. |
| `not_cancelable` | 409 | `conflict_error` | Lượt phân tích này không thể hủy được nữa. |
| `canceled` | 409 | `conflict_error` | Lượt phân tích đã bị hủy. Bạn không bị tính phí. |
| `idempotency_mismatch` | 409 | `conflict_error` | Idempotency-Key này đã được dùng với một nội dung yêu cầu khác. |
| `idempotency_in_progress` | 409 | `conflict_error` | Một yêu cầu có Idempotency-Key này vẫn đang được xử lý. Hãy thử lại sau giây lát. |
| `pending_files_limit` | 429 | `rate_limit_error` | Không gian làm việc này có quá nhiều tệp tải lên đang chờ. Hãy phân tích hoặc xóa các tệp đã tải lên, hoặc chờ tối đa 24 giờ để chúng hết hạn. |
| `rate_limited` | 429 | `rate_limit_error` | Quá nhiều yêu cầu. Hãy thử lại sau số giây ghi trong header Retry-After. |
| `internal_error` | 500 | `api_error` | Không thể hoàn tất yêu cầu. Hãy thử lại; nếu sự cố vẫn tiếp diễn, hãy liên hệ bộ phận hỗ trợ kèm mã yêu cầu. |
| `analysis_failed` | 502 | `api_error` | Không thể hoàn tất lượt phân tích. Bạn không bị tính phí; hãy thử lại, và liên hệ bộ phận hỗ trợ kèm mã yêu cầu nếu lượt phân tích lại thất bại. |
| `service_unavailable` | 503 | `api_error` | Dịch vụ tạm thời không khả dụng hoặc đang bận. Bạn không bị tính phí; hãy thử lại sau số giây ghi trong header Retry-After. |

## Mã chỉ dành cho Console

Các mã này do chính các endpoint của Console trả về; những endpoint đó hoạt động dựa trên phiên đăng nhập của bạn. Các yêu cầu gửi bằng khóa API không trả về chúng.

| Mã lỗi | Trạng thái | Kiểu | Thông báo |
| --- | --- | --- | --- |
| `session_required` | 401 | `authentication_error` | Hãy đăng nhập để tiếp tục. |
| `forbidden` | 403 | `permission_error` | Bạn không có quyền thực hiện thao tác này. |
| `invite_invalid` | 404 | `not_found_error` | Lời mời này không hợp lệ, đã hết hạn hoặc đã được sử dụng. |
| `invite_mismatch` | 403 | `permission_error` | Lời mời này đã được gửi đến một địa chỉ email khác. |
| `invite_limit` | 409 | `conflict_error` | Không gian làm việc này đã đạt số lượng lời mời đang chờ tối đa. Hãy thu hồi bớt một lời mời trước. |
| `last_owner` | 409 | `conflict_error` | Không gian làm việc phải có ít nhất một chủ sở hữu. Hãy chỉ định một thành viên khác làm chủ sở hữu trước. |
| `webhook_limit` | 409 | `conflict_error` | Không gian làm việc này đã đạt số lượng endpoint webhook tối đa. Hãy xóa bớt một endpoint trước. |
| `key_limit` | 409 | `conflict_error` | Không gian làm việc này đã đạt số lượng khóa API đang hoạt động tối đa. Hãy thu hồi bớt một khóa trước. |