ข้อผิดพลาดและขีดจำกัด

รหัสตอบกลับ ความหมาย และวิธีแก้ไข ข้อผิดพลาดทั้งหมดเป็น JSON และมี Request ID.

คู่มือฉบับเต็ม

รูปแบบข้อผิดพลาด

ข้อผิดพลาดจะส่งมาในรูปแบบของ API ที่คุณเรียกใช้: ออบเจ็กต์ error สำหรับ OpenAI, {"type": "error", "error": {...}} สำหรับ Anthropic และ error พร้อมฟิลด์ status และ details สำหรับ Gemini ดังนั้น SDK จึงรู้จักข้อผิดพลาดเหล่านี้เหมือนข้อผิดพลาด API ทั่วไป.

error.code และ error.reason — ประเภทข้อผิดพลาดจากตารางด้านล่าง โดยใช้ค่าเดียวกัน. error.type — ค่ามาตรฐานของรูปแบบนั้น (เช่น invalid_request_error หรือ server_error).
error.request_id (ใน Anthropic คือ request_id ที่ระดับบนสุด), ส่วนหัว X-Request-ID และส่วนท้ายของข้อความ ล้วนระบุตัวระบุคำขอ.
ใน Gemini ประเภทข้อผิดพลาดอยู่ใน error.details: ErrorInfo.reason — เป็นรหัสเดียวกันในรูปตัวพิมพ์ใหญ่ (เช่น MODEL_OVERLOADED), domain — ailoot.aiส่วนตัวระบุคำขออยู่ใน RequestInfo.requestId.
ในรูปแบบ Gemini ข้อผิดพลาด 5xx ที่ห้ามส่งซ้ำโดยอัตโนมัติ และ result_pending_check จะส่งมาด้วยสถานะ 409 และ status ABORTED: เพื่อไม่ให้ Gemini SDK และ CLI ส่งซ้ำเอง ประเภทข้อผิดพลาดอยู่ใน ErrorInfo.reason (เช่น MODEL_TIMEOUT หรือ RESULT_PENDING_CHECK).
ในคำตอบรูปแบบ OpenAI ยังมีฟิลด์ระดับบนสุดอีก code และ message — สำหรับไคลเอนต์รุ่นเก่า.

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

รหัสข้อผิดพลาด

HTTP	ประเภท (reason)	เกิดอะไรขึ้น	สิ่งที่ต้องทำ
400	`invalid_request`	คำขอไม่ถูกต้อง: เนื้อหาหรือพารามิเตอร์ผิด โมเดลไม่รองรับฟิลด์ ไฟล์แนบ หรือเครื่องมือในคำขอ หรือส่งคีย์มาในที่อยู่	แก้ไขคำขอตามข้อความข้อผิดพลาด: ลบฟิลด์ ไฟล์แนบ หรือเครื่องมือที่ไม่รองรับออก และส่งคีย์ในส่วนหัว การปฏิเสธเนื่องจากฟิลด์ ไฟล์แนบ หรือเครื่องมือที่ไม่รองรับเกิดขึ้นก่อนกันวงเงิน จึงไม่มีการหักเงิน
400	`context_length_exceeded`	คำขอยาวเกินขนาดบริบทของโมเดล	ลดประวัติการสนทนาหรือเลือกโมเดลที่มีบริบทใหญ่กว่า
400	`content_policy_violation`	คำขอถูกปฏิเสธตามกฎของโมเดล	ปรับถ้อยคำในคำขอใหม่
401	`invalid_api_key`	ไม่มีคีย์หรือคีย์ไม่ถูกต้อง	ตรวจ⁠สอบว่าส่งคีย์มาครบทั้งค่า
401	`api_key_disabled`	คีย์ถูกปิดใช้งาน	เปิดใช้งานคีย์หรือสร้างคีย์ใหม่
402	`insufficient_balance`, `insufficient_quota`	ยอดเงินที่ยังใช้ได้ไม่พอแม้แต่สำหรับการกันวงเงินขั้นต่ำ (`insufficient_quota` — กรณีเดียวกันในรูปแบบที่ OpenAI SDK คุ้นเคย)	เติมเงินหรือลด max_tokens
402	`api_key_quota_exhausted`	ใช้วงเงินใช้จ่ายรวมของคีย์ครบแล้ว	เพิ่มวงเงินของคีย์ในหน้าบัญชี
402	`payment_disputed`	บัญชีมียอดหนี้จากการชำระเงินที่ถูกโต้แย้ง	ระงับคำขอใหม่จนกว่าจะชำระหนี้ กรุณาติดต่อฝ่ายสนับสนุน
403	`api_key_expired`	คีย์หมดอายุแล้ว	สร้างคีย์ใหม่
403	`account_inactive`	บัญชีของคุณถูกปิดใช้งาน	ติดต่อฝ่ายสนับสนุน
403	`permission_denied`	คีย์ไม่มีสิทธิ์ส่งคำขอนี้ (เช่น เนื่องจาก IP)	ตรวจ⁠สอบข้อจำกัดของคีย์
404	`model_not_found`	ไม่มีโมเดลนี้	ตรวจ⁠สอบ ID เทียบกับ /v1/models
404	`unsupported_endpoint`	โมเดลใช้งานในรูปแบบนี้ไม่ได้	เลือกรูปแบบหรือโมเดลอื่น
404	`not_found`	ไม่มีพาธหรือออบเจ็กต์นี้ (เช่น งาน)	ตรวจ⁠สอบที่อยู่และตัวระบุ
409	`duplicate_request`	ระบบรับการดำเนินการที่ใช้คีย์ idempotency เดียวกันแล้ว และอาจดำเนินการเสร็จแล้ว	ตรวจ⁠สอบผลของการดำเนินการครั้งแรก อย่าส่งครั้งใหม่
409	`not_ready`, `video_not_ready`	วิดีโอหรืองานอื่นยังไม่พร้อม	ขอสถานะอีกครั้งภายหลัง
409, 503	`result_pending_check`	กำลังตรวจ⁠สอบผลของคำขอ สำหรับงานวิดีโอจะระบุด้วยแฟล็ก `result_pending_check: true` ในคำตอบสถานะ โดยตัวงานยังคงอยู่ในสถานะ `in_progress`	อย่าส่งคำขอซ้ำ สถานะจะปรากฏในประวัติ (GET https://ailoot.ai/api/v1/usage) อย่าสร้างงานวิดีโอใหม่ ให้ตรวจ⁠สอบงานเดิมภายหลังผ่าน GET /v1/videos/{id}
410	`model_retired`	โมเดลเลิกให้บริการแล้ว	เลือกเวอร์ชันใหม่จาก GET /v1/models
413	`request_too_large`	เนื้อหาคำขอมีขนาดใหญ่เกินไป	ลดขนาดไฟล์หรือประวัติการสนทนา
429	`rate_limit_exceeded`, `gateway_concurrency_limit`, `gateway_queue_full`	มีคำขอหรือคำขอที่ทำงานพร้อมกันจากบัญชีของคุณมากเกินไป	รอ (ดูส่วนหัว `Retry-After`โดยปกติคือ 10 วินาที) แล้วส่งอีกครั้ง
429	`usage_limit_reached`	ใช้วงเงินของคีย์ครบในช่วงเวลาแล้ว (5 ชั่วโมง, 1 วัน หรือ 7 วัน)	รอจนเริ่มช่วงเวลาใหม่ หรือเพิ่มวงเงินของคีย์
500	`internal_error`	ข้อผิดพลาดของ Ailoot	ติดต่อฝ่ายสนับสนุนพร้อม Request ID
502	`invalid_model_response`, `empty_response`, `incomplete_response`	โมเดลส่งคำตอบที่ไม่ถูกต้อง ว่างเปล่า หรือไม่ครบถ้วน	ค้นหา Request ID ในประวัติของหน้าบัญชี หากมีผลลัพธ์หรือรายการหักเงินอยู่แล้ว การทำซ้ำจะสร้างคำขอแบบเสียเงินครั้งที่สอง การไม่มีรายการไม่ได้ยืนยันว่าคำขอยังไม่ได้ส่งหรือยังไม่ได้ดำเนินการ อย่าส่งซ้ำเมื่อสถานะการส่งไม่ชัดเจน ให้ติดต่อฝ่ายสนับสนุนพร้อม Request ID
502	`result_not_delivered`	ผลลัพธ์ส่งไม่ถึงเนื่องจากข้อผิดพลาดของ Ailoot และได้คืนวงเงินที่กันไว้หรือเงินที่หักไปแล้ว	ส่งคำขอใหม่ได้
503	`model_overloaded`	โมเดลมีภาระงานสูงเกินไปชั่วคราว	หาก X-Should-Retry: true ให้ลองใหม่หลังจากผ่านไปตามจำนวนวินาทีใน Retry-After หากเป็น false ให้ตรวจ⁠สอบ Request ID ในประวัติก่อน
503	`model_unavailable`	โมเดลไม่พร้อมใช้งานชั่วคราว	เลือกโมเดลอื่น หาก X-Should-Retry: true ให้ลองอีกครั้งหลังรอตามจำนวนวินาทีใน Retry-After หากเป็น false ให้ตรวจ⁠สอบ Request ID ในประวัติก่อน
503	`service_unavailable`	ข้อขัดข้องชั่วคราวฝั่ง Ailoot	หาก X-Should-Retry: true ให้ลองใหม่หลังจากผ่านไปตามจำนวนวินาทีใน Retry-After หากเป็น false ให้ตรวจ⁠สอบ Request ID ในประวัติก่อน
503	`charge_not_confirmed`	ไม่ได้ส่งคำตอบ: ยืนยันการหักเงินไม่ได้ คืนวงเงินที่กันไว้แล้ว และไม่มีการหักเงิน	หาก X-Should-Retry: true ให้ลองใหม่หลังจากผ่านไปตามจำนวนวินาทีใน Retry-After หากเป็น false ให้ตรวจ⁠สอบ Request ID ในประวัติก่อน
504	`model_timeout`	โมเดลไม่ตอบภายในเวลาที่กำหนด แต่ผลลัพธ์อาจยังปรากฏภายหลัง	อย่าส่งคำขอซ้ำจนกว่าจะตรวจ⁠สอบ Request ID ในประวัติแล้ว

รหัสสำหรับคำตอบของโมเดลและการตรวจ⁠สอบผลลัพธ์ (502, 503 และ 504) ตอนนี้ใช้ชื่อที่ระบุโมเดลหรือคำขอ: model_unavailable, model_timeout, invalid_model_response, incomplete_response, charge_not_confirmed และ result_pending_check. หากโค้ดของคุณเปรียบเทียบ error.code กับค่าเดิม ให้เปลี่ยนเป็นรหัสจากตาราง หากต้องการทราบว่ารหัสเดิมตรงกับรหัสใหม่ใด โปรดติดต่อ ฝ่ายสนับสนุน.

ควรส่งคำขอซ้ำเมื่อใด

ตรวจ⁠สอบ X-Should-Retry ก่อน: หากเป็น false, result_pending_check หรือ model_timeout อย่าส่งซ้ำโดยอัตโนมัติ ค้นหา Request ID ในประวัติหน้าบัญชีเพื่อดูผลลัพธ์และรายการหักเงิน.
ส่งซ้ำได้อย่างปลอดภัยเมื่อได้รับ X-Should-Retry: true: ให้รอ Retry-After วินาที สำหรับ 5xx การดูแค่รหัสยังไม่พอ เพราะผลลัพธ์อาจเกิดขึ้นแล้ว ให้ตรวจ⁠สอบประวัติในหน้าบัญชีก่อน หรือติดต่อฝ่ายสนับสนุนพร้อม Request ID เรื่องนี้สำคัญเป็นพิเศษสำหรับรูปภาพ วิดีโอ เพลง และขั้นตอนเอเจนต์ที่ใช้เวลานาน.
การส่งซ้ำไม่ช่วย: สำหรับ 400, 401, 402, 403, 404 ให้แก้ไขคำขอ คีย์ หรือยอดเงินก่อน.

ขีดจำกัด

อัตราและจำนวนคำขอที่ทำงานพร้อมกันจำกัดตามบัญชีของคุณโดยรวม ไม่ใช่แยกตามคีย์ หากเกินขีดจำกัดจะได้รับ 429 rate_limit_exceeded พร้อมเฮดเดอร์ Retry-After: 10. หากตัวโมเดลมีภาระงานสูงเกินไป จะได้รับ 503 model_overloaded พร้อม Retry-After: 30. หากต้องการรองรับโหลดมากขึ้น โปรดติดต่อ ฝ่ายสนับสนุน.

กำหนดวงเงินใช้จ่ายได้ที่คีย์: วงเงินรวม — 402 api_key_quota_exhaustedส่วนช่วงเวลา 5 ชั่วโมง, 1 วัน และ 7 วัน — 429 usage_limit_reached. ดูรายละเอียดที่ คีย์และที่อยู่ API.

โมเดล NVIDIA: คิว

ขอรายการโมเดลได้แม้ยอดเงินเป็นศูนย์ แต่การสร้างผลลัพธ์ต้องมีเงินเพียงพอสำหรับกันวงเงิน โมเดล NVIDIA (Nemotron และรุ่นอื่น ๆ) ทำงานผ่านคิวร่วมกัน: เมื่อโหลดสูง คำตอบอาจมาช้าลง หรือได้รับข้อผิดพลาด “โมเดลมีภาระงานสูงเกินไปชั่วคราว” พร้อมส่วนหัว Retry-After ให้ส่งอีกครั้งหลังเวลาที่ระบุ ดูราคาในแค็ตตาล็อก การหักเงินใช้หลักเดียวกับโมเดลอื่น.

ขีดจำกัดด้านขนาดขึ้นอยู่กับโมเดล ได้แก่ บริบท (จำนวนโทเคนที่ส่งได้) และความยาวสูงสุดของคำตอบ โดยระบุไว้ใน แค็ตตาล็อก.

ประวัติและค่าใช้จ่าย

ประวัติและค่าใช้จ่าย · GET https://ailoot.ai/api/v1/usage · JWT · Authorization: Bearer $TOKEN

JWT ≠ sk-… · การเข้าสู่ระบบและเซสชัน

ยังมีคำถามอยู่ใช่ไหม ส่ง Request ID และรายละเอียดมาให้เรา เราจะช่วยตรวจ⁠สอบติดต่อฝ่ายสนับสนุน