Source: https://ailoot.ai/docs/vi/errors/ Canonical: https://ailoot.ai/docs/vi/errors/ Language: vi [Trợ giúp](https://ailoot.ai/docs/vi/) # Lỗi và giới hạn [Markdown](https://ailoot.ai/docs/vi/errors/index.md) Mã phản hồi, ý nghĩa và cách xử lý. Mọi lỗi đều ở dạng JSON và có Request ID. ## [](https://ailoot.ai/docs/vi/errors/#format)Định dạng lỗi Lỗi được trả về theo định dạng của API mà bạn đã gọi: đối tượng `error` cho OpenAI, `{"type": "error", "error": {...}}` cho Anthropic và `error` với các trường `status` và `details` cho Gemini. Vì vậy, SDK nhận diện chúng như các lỗi API thông thường. - `error.code` và `error.reason` — lớp lỗi trong bảng bên dưới; hai giá trị này trùng nhau. `error.type` — giá trị tiêu chuẩn của định dạng (ví dụ, `invalid_request_error` hoặc `server_error`). - `error.request_id` (trong Anthropic là `request_id` ở cấp cao nhất), tiêu đề `X-Request-ID` và phần cuối nội dung thông báo chứa mã định danh yêu cầu. - Trong Gemini, lớp lỗi nằm ở `error.details`: `ErrorInfo.reason` — cùng mã đó viết bằng chữ hoa (ví dụ, `MODEL_OVERLOADED`), `domain` — `ailoot.ai`; mã định danh yêu cầu nằm ở `RequestInfo.requestId`. - Trong định dạng Gemini, lỗi 5xx không được phép tự động thử lại và `result_pending_check` được trả về với trạng thái 409 và `status` `ABORTED`: nhờ vậy, Gemini SDK và CLI không tự gửi lại các yêu cầu đó. Lớp lỗi nằm ở `ErrorInfo.reason` (ví dụ, `MODEL_TIMEOUT` hoặc `RESULT_PENDING_CHECK`). - Phản hồi theo định dạng OpenAI còn có các trường cấp cao nhất `code` và `message` — dành cho ứng dụng khách cũ. ```json { "code": "API_KEY_REQUIRED", "error": { "code": "invalid_api_key", "message": "No API key was sent with the request. Nothing was charged. Please check that the full key is sent in the Authorization header as \"Bearer \". Request ID: 3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6.", "param": null, "reason": "invalid_api_key", "request_id": "3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6", "type": "invalid_request_error" }, "message": "No API key was sent with the request. Nothing was charged. …" } ``` ```json { "type": "error", "error": { "type": "authentication_error", "code": "invalid_api_key", "reason": "invalid_api_key", "message": "… Nothing was charged. … Request ID: 94ed3e31-4373-41ce-bf8a-0d1ed3f7235e." }, "request_id": "94ed3e31-4373-41ce-bf8a-0d1ed3f7235e" } ``` ```json { "error": { "code": 401, "status": "UNAUTHENTICATED", "message": "The API key is not valid. Nothing was charged. … Request ID: e7aa743b-9d0d-4064-b206-2562609f545b.", "details": [ { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "INVALID_API_KEY", "domain": "ailoot.ai", "metadata": { "code": "invalid_api_key", "reason": "invalid_api_key", "request_id": "e7aa743b-9d0d-4064-b206-2562609f545b" } }, { "@type": "type.googleapis.com/google.rpc.RequestInfo", "requestId": "e7aa743b-9d0d-4064-b206-2562609f545b" } ] } } ``` “Nothing was charged” nghĩa là tiền chưa bị trừ. Nếu nhận được X-Should-Retry: false, đừng tự động gửi lại; trước hết hãy kiểm tra Request ID trong lịch sử. ## [](https://ailoot.ai/docs/vi/errors/#codes)Mã lỗi | HTTP | Lớp lỗi (reason) | Điều gì đã xảy ra | Cách xử lý | | --- | --- | --- | --- | | 400 | `invalid_request` | Yêu cầu không hợp lệ: nội dung hoặc tham số sai; mô hình không hỗ trợ trường, tệp đính kèm hoặc công cụ trong yêu cầu; khóa được gửi trong địa chỉ | Sửa yêu cầu theo nội dung lỗi: bỏ trường, tệp đính kèm hoặc công cụ không được hỗ trợ; gửi khóa trong tiêu đề. Việc từ chối do trường, tệp đính kèm hoặc công cụ không được hỗ trợ diễn ra trước khi giữ tiền — chưa có khoản tiền nào bị trừ | | 400 | `context_length_exceeded` | Yêu cầu dài hơn cửa sổ ngữ cảnh của mô hình | Rút ngắn lịch sử hoặc chọn mô hình có cửa sổ ngữ cảnh lớn hơn | | 400 | `content_policy_violation` | Yêu cầu bị từ chối theo quy tắc của mô hình | Diễn đạt lại yêu cầu | | 401 | `invalid_api_key` | Thiếu khóa hoặc khóa không hợp lệ | Kiểm tra xem khóa đã được gửi đầy đủ hay chưa | | 401 | `api_key_disabled` | Khóa đã bị vô hiệu hóa | Bật khóa hoặc tạo khóa mới | | 402 | `insufficient_balance`, `insufficient_quota` | Số dư khả dụng không đủ ngay cả cho khoản giữ trước tối thiểu (`insufficient_quota` — cùng trường hợp đó, ở dạng quen thuộc với OpenAI SDK) | Nạp thêm số dư hoặc giảm max\_tokens | | 402 | `api_key_quota_exhausted` | Đã dùng hết hạn mức chi tiêu tổng của khóa | Tăng hạn mức của khóa trong trang quản lý tài khoản | | 402 | `payment_disputed` | Tài khoản có khoản nợ từ giao dịch thanh toán bị tranh chấp | Tạm dừng yêu cầu mới cho đến khi thanh toán hết nợ — hãy liên hệ bộ phận hỗ trợ | | 403 | `api_key_expired` | Khóa đã hết hạn | Tạo khóa mới | | 403 | `account_inactive` | Tài khoản của bạn đã bị vô hiệu hóa | Liên hệ bộ phận hỗ trợ | | 403 | `permission_denied` | Khóa không được phép thực hiện yêu cầu này (ví dụ, do giới hạn IP) | Kiểm tra các giới hạn của khóa | | 404 | `model_not_found` | Không có mô hình này | Đối chiếu ID với /v1/models | | 404 | `unsupported_endpoint` | Mô hình không hoạt động với định dạng này | Chọn định dạng hoặc mô hình khác | | 404 | `not_found` | Không có đường dẫn hoặc đối tượng này (ví dụ, tác vụ) | Kiểm tra địa chỉ và mã định danh | | 409 | `duplicate_request` | Thao tác có cùng khóa idempotency đã được chấp nhận và có thể đã hoàn tất | Kiểm tra kết quả của thao tác đầu tiên, không gửi thao tác mới | | 409 | `not_ready`, `video_not_ready` | Video hoặc tác vụ khác chưa sẵn sàng | Kiểm tra trạng thái sau | | 409, 503 | `result_pending_check` | Chúng tôi đang xác minh kết quả yêu cầu. Với tác vụ video, đây là cờ `result_pending_check: true` trong phản hồi trạng thái; bản thân tác vụ vẫn ở trạng thái `in_progress` | Không gửi lại yêu cầu — trạng thái sẽ xuất hiện trong lịch sử (GET https://ailoot.ai/api/v1/usage). Đừng tạo lại tác vụ video: hãy kiểm tra tác vụ đó sau qua GET /v1/videos/{id} | | 410 | `model_retired` | Mô hình đã ngừng được cung cấp | Chọn phiên bản mới trong GET /v1/models | | 413 | `request_too_large` | Nội dung yêu cầu quá lớn | Giảm kích thước tệp hoặc rút ngắn lịch sử | | 429 | `rate_limit_exceeded`, `gateway_concurrency_limit`, `gateway_queue_full` | Có quá nhiều yêu cầu hoặc yêu cầu đồng thời từ tài khoản của bạn | Hãy chờ (tiêu đề `Retry-After`, thường là 10 giây) rồi thử lại | | 429 | `usage_limit_reached` | Đã dùng hết hạn mức chi tiêu của khóa trong cửa sổ thời gian (5 giờ, 1 ngày hoặc 7 ngày) | Chờ cửa sổ thời gian được làm mới hoặc tăng hạn mức của khóa | | 500 | `internal_error` | Lỗi Ailoot | Liên hệ bộ phận hỗ trợ và cung cấp Request ID | | 502 | `invalid_model_response`, `empty_response`, `incomplete_response` | Mô hình trả về câu trả lời không hợp lệ, trống hoặc không đầy đủ | Tìm Request ID trong lịch sử của trang tài khoản. Nếu đã có kết quả hoặc khoản ghi nợ, việc gửi lại sẽ tạo yêu cầu trả phí thứ hai. Không có bản ghi không xác nhận rằng yêu cầu chưa được gửi hoặc chưa được thực thi: đừng gửi lại yêu cầu có trạng thái gửi không rõ; hãy liên hệ bộ phận hỗ trợ kèm Request ID. | | 502 | `result_not_delivered` | Kết quả không được chuyển đến do lỗi phía Ailoot; khoản giữ tiền hoặc tiền đã trừ được hoàn lại | Có thể gửi lại yêu cầu | | 503 | `model_overloaded` | Mô hình tạm thời quá tải | Nếu X-Should-Retry: true — thử lại sau số giây trong Retry-After; nếu false — trước tiên kiểm tra Request ID trong lịch sử | | 503 | `model_unavailable` | Mô hình tạm thời không khả dụng | Chọn mô hình khác. Nếu nhận được X-Should-Retry: true, hãy thử lại sau số giây trong Retry-After; nếu là false, trước hết hãy kiểm tra Request ID trong lịch sử | | 503 | `service_unavailable` | Sự cố tạm thời phía Ailoot | Nếu X-Should-Retry: true — thử lại sau số giây trong Retry-After; nếu false — trước tiên kiểm tra Request ID trong lịch sử | | 503 | `charge_not_confirmed` | Câu trả lời không được cung cấp: không thể xác nhận khoản trừ tiền; khoản giữ tiền đã được trả lại và chưa có tiền bị trừ | Nếu X-Should-Retry: true — thử lại sau số giây trong Retry-After; nếu false — trước tiên kiểm tra Request ID trong lịch sử | | 504 | `model_timeout` | Mô hình không trả lời kịp thời; kết quả vẫn có thể xuất hiện sau | Không gửi lại yêu cầu trước khi kiểm tra Request ID trong lịch sử | Các mã cho phản hồi của mô hình và việc xác minh kết quả (502, 503 và 504) hiện nêu mô hình hoặc yêu cầu: `model_unavailable`, `model_timeout`, `invalid_model_response`, `incomplete_response`, `charge_not_confirmed` và `result_pending_check`. Nếu mã của bạn so sánh `error.code` với các giá trị cũ, hãy thay bằng mã trong bảng; để biết mã cũ tương ứng với mã mới nào, hãy hỏi [bộ phận hỗ trợ](https://ailoot.ai/docs/vi/support/). ## [](https://ailoot.ai/docs/vi/errors/#retry)Khi nào nên thử lại yêu cầu - **Trước tiên, hãy xem X-Should-Retry**: nếu là `false`, `result_pending_check` hoặc `model_timeout` thì không tự động gửi lại. Tìm Request ID trong lịch sử của trang quản lý tài khoản: ở đó có kết quả và khoản trừ tiền. - **Việc gửi lại an toàn khi nhận được X-Should-Retry: true**: hãy chờ `Retry-After` giây. Với lỗi 5xx, chỉ mã trạng thái là chưa đủ: kết quả có thể đã có. Trước tiên, hãy kiểm tra lịch sử trong trang quản lý tài khoản hoặc liên hệ hỗ trợ và cung cấp Request ID. Điều này đặc biệt quan trọng với hình ảnh, video, âm nhạc và các bước tác vụ dài của tác nhân. - **Thử lại sẽ không giúp giải quyết lỗi**: 400, 401, 402, 403, 404 — trước hết hãy sửa yêu cầu, khóa hoặc số dư. OpenAI SDK và Anthropic SDK thường tự động gửi lại khi gặp lỗi mạng và 5xx. Hãy tắt hành vi này khi tạo nội dung (`max_retries=0`) và kiểm tra `X-Should-Retry` trước khi thử lại. Không nhận được phản hồi không có nghĩa là yêu cầu chưa được thực hiện. ## [](https://ailoot.ai/docs/vi/errors/#limits)Giới hạn Tần suất và số yêu cầu đồng thời được giới hạn cho toàn bộ tài khoản, không phải cho từng khóa riêng. Khi vượt giới hạn, bạn sẽ nhận được 429 `rate_limit_exceeded` với header `Retry-After: 10`. Nếu chính mô hình bị quá tải, bạn sẽ nhận được 503 `model_overloaded` với `Retry-After: 30`. Nếu cần xử lý tải lớn hơn, hãy liên hệ [bộ phận hỗ trợ](https://ailoot.ai/docs/vi/support/). Hạn mức chi tiêu được đặt cho khóa: hạn mức tổng — 402 `api_key_quota_exhausted`, các cửa sổ 5 giờ, 1 ngày và 7 ngày — 429 `usage_limit_reached`. Xem thêm — [Khóa và địa chỉ API](https://ailoot.ai/docs/vi/keys/#key). ## [](https://ailoot.ai/docs/vi/errors/#nvidia)Mô hình NVIDIA: hàng đợi Bạn có thể lấy danh sách mô hình ngay cả khi số dư bằng không; để tạo nội dung, cần có số dư cho khoản giữ trước. Các mô hình NVIDIA (Nemotron và các mô hình khác) dùng chung một hàng đợi: khi tải cao, câu trả lời có thể đến muộn hơn hoặc có lỗi “mô hình tạm thời quá tải” kèm tiêu đề Retry-After — hãy thử lại sau thời gian được chỉ định. Giá nằm trong danh mục; tiền được trừ như với các mô hình khác. Mô hình quyết định giới hạn kích thước: ngữ cảnh (số token có thể gửi) và độ dài câu trả lời tối đa. Các giới hạn này nằm trong [danh mục](https://ailoot.ai/models/vi/). ## Lịch sử và chi phí [Lịch sử và chi phí](https://ailoot.ai/usage) · [GET https://ailoot.ai/api/v1/usage](https://ailoot.ai/docs/vi/cabinet/usage/) · JWT · `Authorization: Bearer $TOKEN` `JWT ≠ sk-…` · [Đăng nhập và phiên](https://ailoot.ai/docs/vi/cabinet/auth/) Còn câu hỏi? Hãy gửi Request ID và mô tả — chúng tôi sẽ giúp tìm hiểu.[Liên hệ hỗ trợ](mailto:support@ailoot.ai) ## Ailoot · Công ty và danh mục dự án của công ty Ailoot dựa trên kinh nghiệm vận hành tích lũy, cơ sở khách hàng lớn, dịch vụ ổn định và việc kiểm soát KPI liên tục. Công ty và danh mục dự án của công ty: hàng triệu khách hàng; doanh số hàng tỷ mỗi tháng. Ailoot áp dụng kinh nghiệm vận hành này để cung cấp quyền truy cập API vào các tính năng AI trong sản phẩm của khách hàng, tác tử, ứng dụng và quy trình tự động hóa.