จัดการรหัสข้อผิดพลาดสาธารณะของ Rivya API สถานะ HTTP ขีดจำกัดอัตราการเรียก ข้อขัดแย้งจากคำขอซ้ำ และการตัดสินใจลองใหม่

Rivya API ส่งคืนรหัสข้อผิดพลาดสาธารณะที่คงที่ใน JSON ให้ถือค่า error.code เป็นสัญญาสำหรับการเชื่อมต่อระบบ

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

{
  "error": {
    "code": "api_key_missing",
    "message": "A valid Bearer API key is required.",
    "requestId": "req_..."
  }
}

เก็บ requestId ไว้ในบันทึกระบบของคุณ เมื่อขอให้ทีมซัพพอร์ตของ Rivya ตรวจสอบคำขอ API ที่ล้มเหลว

รหัสข้อผิดพลาดที่เสถียร

รหัส	สถานะ HTTP	ความหมาย	การดำเนินการที่แนะนำ
`public_api_disabled`	503	การเรียก API สาธารณะถูกปิดชั่วคราว	ลองใหม่ภายหลัง หรือใช้ Studio ด้วยตัวเองชั่วคราว
`api_key_missing`	401	คำขอไม่มีคีย์ API แบบ Bearer	ส่ง `Authorization: Bearer rvya_sk_...`
`api_key_invalid`	401	ตรวจสอบคีย์ไม่ได้	ตรวจคีย์และหมุนเวียนใหม่หากจำเป็น
`api_key_revoked`	401	คีย์ถูกเพิกถอนในการตั้งค่า	สร้างคีย์ใหม่
`api_key_expired`	401	คีย์ใช้งานไม่ได้แล้ว	สร้างคีย์ใหม่
`api_scope_denied`	403	คีย์ไม่มีขอบเขตสิทธิ์ที่ต้องใช้	สร้างคีย์ที่มีขอบเขตสิทธิ์ที่ต้องการ
`rate_limited`	429	มีคำขอมากเกินไปในช่วงเวลาปัจจุบัน	เว้นระยะแล้วลองใหม่ภายหลัง
`validation_failed`	400	เนื้อหาคำขอ โมเดล พรอมต์ หรือพารามิเตอร์ไม่ถูกต้อง	เทียบเนื้อหาคำขอกับเอกสารอ้างอิงโมเดล
`not_found`	404	งานที่ขอไม่มีอยู่ หรือไม่ได้เป็นของบัญชีนี้	ตรวจรหัสงานสาธารณะและขอบเขตบัญชี
`webhook_url_rejected`	400	URL ของจุดเชื่อมต่อเว็บฮุกไม่ได้รับอนุญาต	ใช้ URL HTTPS สาธารณะที่ไม่มีข้อมูลรับรอง ชื่อโฮสต์ของเครื่อง หรือที่อยู่เครือข่ายภายใน
`chat_model_not_supported`	400	โมเดลที่เลือกยังไม่พร้อมใช้งานกับ Chat API	อ่าน `/api/v1/models` แล้วเลือก chat model ที่พร้อมใช้งาน
`chat_session_conflict`	409	เซสชันแชตใช้กับคำขอนี้ไม่ได้	ใช้เซสชันที่สร้างผ่าน API ซึ่งเป็นของบัญชีและโมเดลเดียวกัน
`chat_attachment_not_supported`	400	ไม่รองรับไฟล์แนบแชตนี้	อัปโหลดรูปภาพผ่าน Files API แล้วส่ง `file_id`
`idempotency_conflict`	409	ใช้คีย์ป้องกันคำขอซ้ำเดียวกันกับอินพุตที่ต่างกัน	ใช้คีย์ใหม่ หรือส่งเนื้อหาคำขอเดิมทุกประการอีกครั้ง
`insufficient_credits`	402	บัญชีมีเครดิตไม่พอ	เติมเครดิตหรือเลือกคำขอที่ใช้ต้นทุนต่ำลง
`internal_error`	500	ดำเนินการตามคำขอไม่สำเร็จ	ลองใหม่ด้วยคีย์ป้องกันคำขอซ้ำ หรือติดต่อซัพพอร์ตพร้อม `requestId`

ขีดจำกัดอัตราการเรียก

Rivya จำกัดอัตราการเรียก Public API ต่อคีย์ในระดับแอปพลิเคชัน โดยค่าเริ่มต้นของระบบจริงกำหนดผ่าน PUBLIC_API_RATE_LIMIT_PER_MINUTE

เมื่อได้รับ rate_limited ให้เพิ่มช่วงเวลารอก่อนลองใหม่แบบทวีคูณ และอย่าวนเรียกซ้ำถี่ๆ

การลองใหม่โดยไม่ทำงานซ้ำ

ส่ง Idempotency-Key กับคำขอในระบบจริงทุกครั้งที่เรียก POST /api/v1/generations และ POST /api/v1/chat/completions

รูปแบบที่แนะนำ:

สร้างคีย์ที่ไม่ซ้ำกันสำหรับคำขอสร้างงานแต่ละรายการ
ใช้คีย์เดิมซ้ำเฉพาะเมื่อลองใหม่ด้วยเนื้อหาคำขอเดิม
เก็บรหัสงานสาธารณะที่ได้รับไว้กับบันทึกงานของคุณ
สำหรับ Chat API ให้เก็บ session_id ที่ได้รับไว้เมื่อต้องการสนทนาต่อในบทสนทนาเดิม
อย่าใช้คีย์เดียวกันกับโมเดล พรอมต์ หรือพารามิเตอร์ที่ต่างกัน

หากเครือข่ายล้มเหลวหลังส่งคำขอ ให้ลองใหม่ด้วยเนื้อหาคำขอและ Idempotency-Key เดิม Rivya สามารถคืนคำตอบสาธารณะที่บันทึกไว้แทนการสร้างงานซ้ำ

การตัดสินใจลองใหม่

ลองใหม่สำหรับข้อผิดพลาดเหล่านี้โดยเพิ่มช่วงเวลารอ:

public_api_disabled
rate_limited
internal_error
เครือข่ายขัดข้องชั่วคราว

อย่าลองใหม่สำหรับข้อผิดพลาดเหล่านี้โดยไม่เปลี่ยนอินพุต:

api_key_invalid
api_key_revoked
api_scope_denied
validation_failed
webhook_url_rejected
chat_model_not_supported
chat_session_conflict
chat_attachment_not_supported
idempotency_conflict
insufficient_credits

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

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

รหัสข้อผิดพลาดที่เสถียร

ขีดจำกัดอัตราการเรียก

การลองใหม่โดยไม่ทำงานซ้ำ

การตัดสินใจลองใหม่

หน้าที่เกี่ยวข้อง

สารบัญ