Lỗi và giới hạn

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ũ.

{
  "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 <key>\". 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. …"
}

{
  "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"
}

{
  "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"
      }
    ]
  }
}

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ợ.

• 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ư.

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ợ.

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.

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.