จัดการ public error codes ของ Rivya API, ค่า HTTP status, rate limits, idempotency conflicts และการตัดสินใจลองใหม่

Rivya API ส่งคืน public error codes ที่เสถียรใน JSON ให้ถือค่า error.code เป็นสัญญาสำหรับการเชื่อมต่อระบบ

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

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

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

Error Codes ที่เสถียร

Code	HTTP status	ความหมาย	การดำเนินการที่แนะนำ
`public_api_disabled`	503	การเรียก Public API ถูกปิดชั่วคราว	ลองใหม่ภายหลัง หรือใช้ Studio ด้วยตัวเองชั่วคราว
`api_key_missing`	401	request ไม่ได้ใส่ Bearer API key	ส่ง `Authorization: Bearer rvya_sk_...`
`api_key_invalid`	401	key ตรวจสอบไม่ได้	ตรวจ key และหมุนเวียนใหม่หากจำเป็น
`api_key_revoked`	401	key ถูกเพิกถอนใน Settings	สร้าง key ใหม่
`api_key_expired`	401	key ใช้งานไม่ได้แล้ว	สร้าง key ใหม่
`api_scope_denied`	403	key ไม่มี scope ที่ต้องใช้	สร้าง key ที่มี scope ที่ต้องการ
`rate_limited`	429	request ในช่วงเวลาปัจจุบันมากเกินไป	ถอยระยะแล้วลองใหม่ภายหลัง
`validation_failed`	400	body, model, prompt หรือ params ไม่ถูกต้อง	เทียบ body ของคุณกับ model reference
`not_found`	404	task ที่ขอไม่มีอยู่ หรือไม่ได้เป็นของบัญชีนี้	ตรวจ public task ID และขอบเขตบัญชี
`webhook_url_rejected`	400	webhook endpoint URL ไม่ได้รับอนุญาต	ใช้ HTTPS public URL ที่ไม่มี credentials, fragments, localhost หรือ private network addresses
`chat_model_not_supported`	400	โมเดลที่เลือกยังไม่พร้อมใช้งานกับ Chat API	อ่าน `/api/v1/models` แล้วเลือก chat model ที่พร้อมใช้งาน
`chat_session_conflict`	409	chat session ใช้กับ request นี้ไม่ได้	ใช้ session ที่สร้างผ่าน API ซึ่งเป็นของบัญชีและโมเดลเดียวกัน
`chat_attachment_not_supported`	400	ไม่รองรับ chat attachment นี้	อัปโหลดรูปภาพผ่าน Files API แล้วส่ง `file_id`
`idempotency_conflict`	409	idempotency key เดียวกันถูกใช้ซ้ำกับ input ที่ต่างกัน	ใช้ key ใหม่ หรือส่ง body เดิมทุกประการอีกครั้ง
`insufficient_credits`	402	บัญชีมีเครดิตไม่พอ	เติมเครดิตหรือเลือก request ที่ต้นทุนต่ำลง
`internal_error`	500	request ทำไม่สำเร็จ	ลองใหม่ด้วย idempotency หรือติดต่อซัพพอร์ตพร้อม `requestId`

ขีดจำกัดอัตราการเรียก (Rate Limits)

Rivya ใช้ application-level Public API rate limits ต่อ API key ค่า production เริ่มต้นกำหนดโดย PUBLIC_API_RATE_LIMIT_PER_MINUTE

เมื่อได้รับ rate_limited ให้ใช้ exponential backoff อย่าลองใหม่แบบวนถี่

retry แบบ idempotent

ส่ง Idempotency-Key กับทุก request production ที่เป็น POST /api/v1/generations และ POST /api/v1/chat/completions

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

สร้าง key ที่ไม่ซ้ำกันต่อ logical generation request
ใช้ key เดิมซ้ำเฉพาะเมื่อลองใหม่ด้วย body เดิม
เก็บ public task ID ที่ได้กลับมากับ job record ของคุณเอง
สำหรับ Chat API ให้เก็บ session_id ที่ได้กลับมาเมื่อต้องการสนทนาต่อใน conversation เดิม
อย่าใช้ key เดียวกันกับ model, prompt หรือ params ที่ต่างกัน

หาก network ล้มเหลวหลังส่ง request แล้ว ให้ลองใหม่ด้วย body เดิมและ Idempotency-Key เดิม Rivya สามารถคืน public response ที่บันทึกไว้แทนการสร้าง task ซ้ำ

การตัดสินใจ Retry

ลองใหม่สำหรับ error เหล่านี้ด้วย backoff:

public_api_disabled
rate_limited
internal_error
ความล้มเหลวของ network ชั่วคราว

อย่าลองใหม่สำหรับ error เหล่านี้โดยไม่เปลี่ยน input:

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

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

Error Codes ที่เสถียร

ขีดจำกัดอัตราการเรียก (Rate Limits)

retry แบบ idempotent

การตัดสินใจ Retry

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

สารบัญ